@profplum700/etsy-v3-api-client 2.3.1 → 2.3.9

package/dist/index.d.ts

@@ -292,19 +292,33 @@ interface EtsyErrorDetails {
     field?: string;
     suggestion?: string;
     retryAfter?: number;
+    endpoint?: string;
+    timestamp?: Date;
+    validationErrors?: Array<{
+        field: string;
+        message: string;
+    }>;
 }
 declare class EtsyApiError extends Error {
     _statusCode?: number | undefined;
     _response?: unknown | undefined;
     _retryAfter?: number | undefined;
     details: EtsyErrorDetails;
-    constructor(message: string, _statusCode?: number | undefined, _response?: unknown | undefined, _retryAfter?: number | undefined);
+    readonly endpoint?: string;
+    readonly suggestions: string[];
+    readonly docsUrl: string;
+    readonly timestamp: Date;
+    constructor(message: string, _statusCode?: number | undefined, _response?: unknown | undefined, _retryAfter?: number | undefined, endpoint?: string);
     get statusCode(): number | undefined;
     get response(): unknown | undefined;
     isRetryable(): boolean;
     getRetryAfter(): number | null;
     getRateLimitReset(): Date | null;
+    private generateSuggestions;
+    private generateDocsUrl;
     getUserFriendlyMessage(): string;
+    toString(): string;
+    toJSON(): Record<string, unknown>;
 }
 declare class EtsyAuthError extends Error {
     _code?: string | undefined;
@@ -1210,6 +1224,44 @@ declare class EtsyRateLimiter {
 }
 declare const defaultRateLimiter: EtsyRateLimiter;
 
+type RequestPriority = 'high' | 'normal' | 'low';
+interface QueueOptions {
+    priority?: RequestPriority;
+    timeout?: number;
+    endpoint?: string;
+}
+declare class GlobalRequestQueue {
+    private static instance;
+    private queue;
+    private processing;
+    private rateLimits;
+    private requestCount;
+    private dailyReset;
+    private lastRequestTime;
+    private readonly maxRequestsPerDay;
+    private readonly maxRequestsPerSecond;
+    private readonly minRequestInterval;
+    private constructor();
+    static getInstance(): GlobalRequestQueue;
+    static resetInstance(): void;
+    enqueue<T>(request: () => Promise<T>, options?: QueueOptions): Promise<T>;
+    getStatus(): {
+        queueLength: number;
+        processing: boolean;
+        remainingRequests: number;
+        resetTime: Date;
+    };
+    clear(): void;
+    private processQueue;
+    private waitForRateLimit;
+    private updateRateLimitInfo;
+    private setNextDailyReset;
+    private generateId;
+    private delay;
+}
+declare function getGlobalQueue(): GlobalRequestQueue;
+declare function withQueue<T>(request: () => Promise<T>, options?: QueueOptions): Promise<T>;
+
 interface PaginationOptions {
     limit?: number;
     offset?: number;
@@ -1516,6 +1568,97 @@ declare class WebhookSecurity {
 }
 declare function createWebhookSecurity(secret: string, algorithm?: 'sha256' | 'sha1' | 'sha512'): WebhookSecurity;
 
+interface SecureTokenStorageConfig {
+    keyPrefix?: string;
+    derivationInput?: string;
+    useSessionStorage?: boolean;
+}
+declare class SecureTokenStorage implements TokenStorage {
+    private readonly keyPrefix;
+    private readonly derivationInput;
+    private readonly storage;
+    private encryptionKey;
+    constructor(config?: SecureTokenStorageConfig);
+    save(tokens: EtsyTokens): Promise<void>;
+    load(): Promise<EtsyTokens | null>;
+    clear(): Promise<void>;
+    private getEncryptionKey;
+    private deriveKeyMaterial;
+    private generateIntegrity;
+    private getDefaultDerivationInput;
+    private stringToArrayBuffer;
+    private arrayBufferToBase64;
+    private base64ToArrayBuffer;
+    private compareArrayBuffers;
+}
+declare function isSecureStorageSupported(): boolean;
+
+interface PluginRequestConfig {
+    method: string;
+    endpoint: string;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+interface PluginResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers?: Record<string, string>;
+}
+interface EtsyPlugin {
+    name: string;
+    version?: string;
+    onBeforeRequest?: (config: PluginRequestConfig) => Promise<PluginRequestConfig> | PluginRequestConfig;
+    onAfterResponse?: <T>(response: PluginResponse<T>) => Promise<PluginResponse<T>> | PluginResponse<T>;
+    onError?: (error: Error) => Promise<void> | void;
+    onInit?: () => Promise<void> | void;
+    onDestroy?: () => Promise<void> | void;
+}
+declare class PluginManager {
+    private plugins;
+    register(plugin: EtsyPlugin): Promise<void>;
+    unregister(pluginName: string): Promise<boolean>;
+    getPlugins(): ReadonlyArray<EtsyPlugin>;
+    getPlugin(name: string): EtsyPlugin | undefined;
+    executeBeforeRequest(config: PluginRequestConfig): Promise<PluginRequestConfig>;
+    executeAfterResponse<T>(response: PluginResponse<T>): Promise<PluginResponse<T>>;
+    executeOnError(error: Error): Promise<void>;
+    clear(): Promise<void>;
+}
+interface AnalyticsPluginConfig {
+    trackingId: string;
+    trackEndpoint?: (endpoint: string, method: string, duration: number) => void;
+    trackError?: (error: Error) => void;
+}
+declare function createAnalyticsPlugin(config: AnalyticsPluginConfig): EtsyPlugin;
+interface RetryPluginConfig {
+    maxRetries?: number;
+    retryDelay?: number;
+    retryableStatusCodes?: number[];
+    onRetry?: (attempt: number, error: Error) => void;
+}
+declare function createRetryPlugin(config?: RetryPluginConfig): EtsyPlugin;
+interface LoggingPluginConfig {
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    logger?: {
+        debug: (message: string, ...args: unknown[]) => void;
+        info: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
+}
+declare function createLoggingPlugin(config?: LoggingPluginConfig): EtsyPlugin;
+interface CachingPluginConfig {
+    ttl?: number;
+    keyGenerator?: (config: PluginRequestConfig) => string;
+}
+declare function createCachingPlugin(config?: CachingPluginConfig): EtsyPlugin;
+interface RateLimitPluginConfig {
+    maxRequestsPerSecond?: number;
+    onRateLimitExceeded?: () => void;
+}
+declare function createRateLimitPlugin(config?: RateLimitPluginConfig): EtsyPlugin;
+
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 declare const hasLocalStorage: boolean;
@@ -1556,5 +1699,5 @@ declare function getLibraryInfo(): {
     homepage: string;
 };
 
-export { AuthHelper, BatchQueryExecutor, BulkOperationManager, COMMON_SCOPE_COMBINATIONS, CacheWithInvalidation, CreateListingSchema, DEFAULT_RETRY_CONFIG, ETSY_SCOPES, EncryptedFileTokenStorage, EtsyApiError, EtsyAuthError, EtsyClient, EtsyRateLimitError, EtsyRateLimiter, EtsyWebhookHandler, FieldValidator, FileTokenStorage, LFUCache, LIBRARY_NAME, LRUCache, ListingQueryBuilder, LocalStorageTokenStorage, MemoryTokenStorage, PaginatedResults, ReceiptQueryBuilder, RedisCacheStorage, RetryManager, SessionStorageTokenStorage, TokenManager, UpdateListingSchema, UpdateShopSchema, VERSION, ValidationException, Validator, WebhookSecurity, combineValidators, createAuthHelper, createBatchQuery, createBulkOperationManager, createCacheStorage, createCacheWithInvalidation, createCodeChallenge, createDefaultTokenStorage, createEtsyClient, createListingQuery, createPaginatedResults, createRateLimiter, createReceiptQuery, createRedisCacheStorage, createTokenManager, createValidator, createWebhookHandler, createWebhookSecurity, decryptAES256GCM, EtsyClient as default, defaultRateLimiter, deriveKeyFromPassword, encryptAES256GCM, executeBulkOperation, field, generateCodeVerifier, generateEncryptionKey, generateRandomBase64Url, generateState, getAvailableStorage, getEnvironmentInfo, getLibraryInfo, hasLocalStorage, hasSessionStorage, isBrowser, isNode, sha256, sha256Base64Url, validate, validateEncryptionKey, validateOrThrow, withQueryBuilder, withRetry };
-export type { AdvancedCachingConfig, AuthHelperConfig, BulkImageUploadOperation, BulkOperationConfig, BulkOperationError, BulkOperationResult, BulkOperationSummary, BulkUpdateListingOperation, CacheEntry, CacheStats, CacheStorage, CacheStrategy, 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, EtsySellerTaxonomyNode, EtsyShippingProfile, EtsyShippingProfileDestination, EtsyShippingProfileUpgrade, EtsyShop, EtsyShopProductionPartner, EtsyShopReceipt, EtsyShopReceiptShipment, EtsyShopReceiptTransaction, EtsyShopRefund, EtsyShopSection, EtsyTokenResponse, EtsyTokens, EtsyTransactionVariation, EtsyUser, EtsyWebhookEvent, EtsyWebhookEventType, GetPaymentAccountLedgerEntriesParams, GetShopReceiptsParams, ListingParams, ListingSortOn, ListingState, LoggerInterface, PageFetcher, PaginationOptions, RateLimitConfig, RateLimitStatus, RedisClientLike, RedisConfig, RetryConfig, RetryOptions, SearchParams, SortOrder, TokenRefreshCallback, TokenRotationCallback, TokenRotationConfig, TokenStorage, UpdateListingInventoryParams, UpdateListingParams, UpdateShippingProfileDestinationParams, UpdateShippingProfileParams, UpdateShopParams, UpdateShopReceiptParams, UpdateShopSectionParams, UploadListingFileParams, UploadListingImageParams, ValidationError, ValidationOptions, ValidationResult, ValidationSchema, ValidatorFunction, WebhookConfig, WebhookEventHandler, WebhookSecurityConfig };
+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 };