@profplum700/etsy-v3-api-client

interface EtsyClientConfig { keystring: string; sharedSecret: string; accessToken: string; refreshToken: string; expiresAt: Date; refreshSave?: (_accessToken: string, _refreshToken: string, _expiresAt: Date) => void; baseUrl?: string; rateLimiting?: { enabled: boolean; 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; ttl?: number; storage?: CacheStorage; }; } interface AuthHelperConfig { keystring: string; redirectUri: string; scopes: string[]; codeVerifier?: string; state?: string; } interface EtsyTokens { access_token: string; refresh_token: string; expires_at: Date; token_type: string; scope: string; } interface EtsyTokenResponse { access_token: string; token_type: string; expires_in: number; refresh_token: string; scope: string; } type TokenRefreshCallback = (_accessToken: string, _refreshToken: string, _expiresAt: Date) => void; type TokenRotationCallback = (oldTokens: EtsyTokens, newTokens: EtsyTokens) => void | Promise<void>; interface TokenStorage { save(_tokens: EtsyTokens): Promise<void>; load(): Promise<EtsyTokens | null>; clear(): Promise<void>; } interface TokenRotationConfig { enabled: boolean; rotateBeforeExpiry: number; onRotation?: TokenRotationCallback; autoSchedule?: boolean; checkInterval?: number; } interface EtsyPagination { next_offset?: number; effective_limit?: number; effective_offset?: number; } interface EtsyApiResponse<T> { count: number; results: T[]; pagination?: EtsyPagination; } interface EtsyUser { user_id: number; shop_id?: number; login_name?: string; primary_email?: string; first_name?: string; last_name?: string; create_timestamp?: number; created_timestamp?: number; bio?: string; gender?: string; birth_month?: string; birth_day?: string; birth_year?: string; join_tsz?: number; city?: string; country_id?: number; region?: string; image_url_75x75?: string; num_favorers?: number; } interface EtsyShop { shop_id: number; shop_name: string; user_id: number; create_date: number; title?: string; announcement?: string; currency_code: string; is_vacation: boolean; vacation_message?: string; sale_message?: string; digital_sale_message?: string; last_updated_tsz: number; listing_active_count: number; digital_listing_count: number; login_name: string; accepts_custom_requests: boolean; policy_welcome?: string; policy_payment?: string; policy_shipping?: string; policy_refunds?: string; policy_additional?: string; policy_seller_info?: string; policy_updated_tsz?: number; policy_has_private_receipt_info: boolean; has_unstructured_policies: boolean; policy_privacy?: string; vacation_autoreply?: string; url: string; image_url_760x100?: string; num_favorers: number; languages: string[]; upcoming_local_event_id?: number; icon_url_fullxfull?: string; is_using_structured_policies: boolean; has_onboarded_structured_policies: boolean; include_dispute_form_link: boolean; is_direct_checkout_onboarded: boolean; is_calculated_eligible: boolean; is_opted_in_to_buyer_promise: boolean; is_shop_us_based: boolean; transaction_sold_count: number; shipping_from_country_iso: string; shop_location_country_iso: string; review_count: number; review_average: number; } interface EtsyShopSection { shop_section_id: number; title: string; rank: number; user_id: number; active_listing_count: number; } interface EtsyListing { listing_id: number; title: string; description?: string; price: { amount: number; divisor: number; currency_code: string; }; url: string; images?: Array<{ url_570xN: string; alt_text?: string; }>; when_made?: string; shop_section_id?: number; tags?: string[]; materials?: string[]; style?: string[]; item_length?: number; item_width?: number; item_height?: number; item_dimensions_unit?: string; state?: 'active' | 'inactive' | 'sold_out' | 'draft' | 'expired'; creation_tsz?: number; ending_tsz?: number; original_creation_tsz?: number; last_modified_tsz?: number; views?: number; num_favorers?: number; shop_id?: number; user_id?: number; category_id?: number; is_supply?: boolean; is_private?: boolean; recipient?: string; occasion?: string; style_id?: number[]; non_taxable?: boolean; is_personalizable?: boolean; personalization_is_required?: boolean; personalization_char_count_max?: number; personalization_instructions?: string; is_customizable?: boolean; is_digital?: boolean; file_data?: string; can_write_inventory?: boolean; has_variations?: boolean; should_auto_renew?: boolean; language?: string; processing_min?: number; processing_max?: number; who_made?: string; is_mass_produced?: boolean; item_weight?: number; item_weight_unit?: string; shipping_template_id?: number; featured_rank?: number; skus?: string[]; used_manufacturer?: boolean; } interface EtsyReview { review_id?: number; rating?: number; review?: string; language?: string; created_timestamp?: number; created_tsz?: number; listing_id?: number; shop_id?: number; [key: string]: unknown; } interface EtsyListingImage { listing_image_id: number; hex_code?: string; red?: number; green?: number; blue?: number; hue?: number; saturation?: number; brightness?: number; is_black_and_white?: boolean; creation_tsz?: number; listing_id?: number; rank?: number; url_75x75?: string; url_170x135?: string; url_570xN?: string; url_fullxfull?: string; full_height?: number; full_width?: number; alt_text?: string; } interface EtsyListingInventory { products: EtsyListingProduct[]; price_on_property?: number[]; quantity_on_property?: number[]; sku_on_property?: number[]; readiness_state_on_property?: number[]; } interface EtsyListingProduct { product_id: number; sku?: string; is_deleted?: boolean; offerings: EtsyListingOffering[]; property_values?: EtsyListingPropertyValue[]; } interface EtsyListingOffering { offering_id: number; price: { amount: number; divisor: number; currency_code: string; }; quantity: number; is_enabled: boolean; is_deleted: boolean; readiness_state_id?: number; } interface EtsyListingPropertyValue { property_id: number; property_name: string; scale_id?: number; scale_name?: string; value_ids?: number[]; values?: string[]; } interface EtsySellerTaxonomyNode { id: number; level: number; name: string; parent_id: number | null; children: EtsySellerTaxonomyNode[]; full_path_taxonomy_ids: number[]; } interface ListingParams { limit?: number; offset?: number; state?: 'active' | 'inactive' | 'sold_out' | 'draft' | 'expired'; sort_on?: 'created' | 'price' | 'updated' | 'score'; sort_order?: 'asc' | 'ascending' | 'desc' | 'descending' | 'up' | 'down'; includes?: ListingIncludes[]; legacy?: boolean; } type ListingIncludes = 'Shipping' | 'Images' | 'Shop' | 'User' | 'Translations' | 'Inventory' | 'Videos'; type EtsyPersonalizationQuestionType = 'text_input' | 'dropdown' | 'unlabeled_upload' | 'labeled_upload'; interface EtsyPersonalizationOption { option_id?: number | null; label: string; } interface EtsyPersonalizationQuestion { question_id?: number | null; question_type: EtsyPersonalizationQuestionType; question_text: string; instructions?: string | null; required: boolean; max_allowed_characters?: number | null; max_allowed_files?: number | null; options?: EtsyPersonalizationOption[] | null; } interface EtsyListingPersonalization { personalization_questions: EtsyPersonalizationQuestion[]; } interface UpdatePersonalizationParams { personalization_questions: EtsyPersonalizationQuestion[]; supports_multiple_personalization_questions?: boolean; } interface SearchParams { limit?: number; offset?: number; keywords?: string; sort_on?: 'created' | 'price' | 'updated' | 'score'; sort_order?: 'asc' | 'ascending' | 'desc' | 'descending' | 'up' | 'down'; min_price?: number; max_price?: number; taxonomy_id?: number; shop_location?: string; legacy?: boolean; } interface GetListingParams { includes?: ListingIncludes[]; language?: string; legacy?: boolean; allow_suggested_title?: boolean; } type ListingInventoryIncludes = 'Listing'; interface GetListingInventoryParams { show_deleted?: boolean; includes?: ListingInventoryIncludes; legacy?: boolean; } interface GetReviewsParams { limit?: number; offset?: number; min_created?: number; max_created?: number; } 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; errorCode?: string; 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; 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; constructor(message: string, _code?: string | undefined); get code(): string | undefined; } declare class EtsyRateLimitError extends Error { _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>; set(_key: string, _value: string, _ttl?: number): Promise<void>; delete(_key: string): Promise<void>; clear(): Promise<void>; } interface LoggerInterface { 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 const ETSY_WHEN_MADE_VALUES: readonly ["1990s", "1980s", "1970s", "1960s", "1950s", "1940s", "1930s", "1920s", "1910s", "1900s", "1800s", "1700s", "before_1700"]; interface UpdateShopParams { title?: string; announcement?: string; sale_message?: string; digital_sale_message?: string; policy_additional?: string; } interface CreateShopSectionParams { title: string; } interface UpdateShopSectionParams { title: string; } interface EtsyShopReceipt { receipt_id: number; receipt_type: number; seller_user_id: number; seller_email: string; buyer_user_id: number; buyer_email: string; name: string; first_line: string; second_line?: string; city: string; state?: string; zip: string; status: 'open' | 'completed' | 'payment-processing' | 'canceled'; formatted_address: string; country_iso: string; payment_method: string; payment_email?: string; message_from_seller?: string; message_from_buyer?: string; message_from_payment?: string; is_paid: boolean; is_shipped: boolean; create_timestamp: number; created_timestamp: number; update_timestamp: number; updated_timestamp: number; is_gift: boolean; gift_message?: string; grandtotal: { amount: number; divisor: number; currency_code: string; }; subtotal: { amount: number; divisor: number; currency_code: string; }; total_price: { amount: number; divisor: number; currency_code: string; }; total_shipping_cost: { amount: number; divisor: number; currency_code: string; }; total_tax_cost: { amount: number; divisor: number; currency_code: string; }; total_vat_cost: { amount: number; divisor: number; currency_code: string; }; discount_amt: { amount: number; divisor: number; currency_code: string; }; gift_wrap_price: { amount: number; divisor: number; currency_code: string; }; shipments?: EtsyShopReceiptShipment[]; transactions?: EtsyShopReceiptTransaction[]; refunds?: EtsyShopRefund[]; } interface EtsyShopReceiptTransaction { transaction_id: number; title: string; description: string; seller_user_id: number; buyer_user_id: number; create_timestamp: number; created_timestamp: number; paid_timestamp: number; shipped_timestamp: number; quantity: number; listing_image_id?: number; receipt_id: number; is_digital: boolean; file_data: string; listing_id: number; transaction_type: string; product_id?: number; sku?: string; price: { amount: number; divisor: number; currency_code: string; }; shipping_cost: { amount: number; divisor: number; currency_code: string; }; variations?: EtsyTransactionVariation[]; product_data?: EtsyListingProduct[]; shipping_profile_id?: number; min_processing_days?: number; max_processing_days?: number; shipping_method?: string; shipping_upgrade?: string; expected_ship_date?: number; buyer_coupon?: number; shop_coupon?: number; } interface EtsyTransactionVariation { property_id: number; value_id: number; formatted_name: string; formatted_value: string; } interface EtsyShopReceiptShipment { receipt_shipping_id: number; shipment_notification_timestamp: number; carrier_name: string; tracking_code: string; } interface EtsyShopRefund { amount: { amount: number; divisor: number; currency_code: string; }; created_timestamp: number; reason?: string; note_from_issuer?: string; status: string; } interface GetShopReceiptsParams { limit?: number; offset?: number; sort_on?: 'created' | 'updated' | 'receipt_id'; sort_order?: 'asc' | 'ascending' | 'desc' | 'descending' | 'up' | 'down'; min_created?: number; max_created?: number; min_last_modified?: number; max_last_modified?: number; was_paid?: boolean; was_shipped?: boolean; was_delivered?: boolean; was_canceled?: boolean; legacy?: boolean; } interface GetShopReceiptParams { legacy?: boolean; } interface GetShopReceiptTransactionsParams { legacy?: boolean; } interface UpdateShopReceiptParams { was_shipped?: boolean; was_paid?: boolean; } interface EtsyShippingProfile { shipping_profile_id: number; title: string; user_id: number; origin_country_iso: string; is_deleted?: boolean; origin_postal_code?: string; profile_type: 'manual' | 'calculated'; domestic_handling_fee?: number; international_handling_fee?: number; shipping_profile_destinations?: EtsyShippingProfileDestination[]; shipping_profile_upgrades?: EtsyShippingProfileUpgrade[]; } interface EtsyShippingProfileDestination { shipping_profile_destination_id: number; shipping_profile_id: number; origin_country_iso: string; destination_country_iso?: string; destination_region: string; primary_cost: { amount: number; divisor: number; currency_code: string; }; secondary_cost: { amount: number; divisor: number; currency_code: string; }; shipping_carrier_id?: number; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; } interface EtsyShippingProfileUpgrade { shipping_profile_id: number; upgrade_id: number; upgrade_name: string; type: string; rank: number; language: string; price: { amount: number; divisor: number; currency_code: string; }; secondary_price: { amount: number; divisor: number; currency_code: string; }; shipping_carrier_id: number; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; } interface CreateShippingProfileParams { title: string; origin_country_iso: string; primary_cost: number; secondary_cost: number; min_processing_time?: number; max_processing_time?: number; processing_time_unit?: string; shipping_carrier_id?: number; origin_postal_code?: string; destination_country_iso?: string; destination_region?: string; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; } interface UpdateShippingProfileParams { title?: string; origin_country_iso?: string; min_processing_time?: number; max_processing_time?: number; processing_time_unit?: string; origin_postal_code?: string; } interface CreateShippingProfileDestinationParams { primary_cost: number; secondary_cost: number; destination_country_iso?: string; destination_region?: string; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; shipping_carrier_id?: number; } interface UpdateShippingProfileDestinationParams { primary_cost?: number; secondary_cost?: number; destination_country_iso?: string; destination_region?: string; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; shipping_carrier_id?: number; } interface GetShippingProfileDestinationsParams { limit?: number; offset?: number; } interface CreateReceiptShipmentParams { tracking_code: string; carrier_name: string; send_bcc?: boolean; note_to_buyer?: string; } interface EtsyPaymentAccountLedgerEntry { entry_id: number; ledger_id: number; sequence_number: number; amount: { amount: number; divisor: number; currency_code: string; }; currency: string; description: string; balance: { amount: number; divisor: number; currency_code: string; }; create_date: number; created_timestamp: number; ledger_type: string; entry_type: string; reference_type?: string; reference_id?: string; payment_adjustments?: EtsyPaymentAdjustment[]; } interface EtsyPaymentAdjustment { payment_adjustment_id: number; payment_id: number; status: string; is_success: boolean; user_id: number; reason_code: string; total_adjustment_amount: { amount: number; divisor: number; currency_code: string; }; shop_total_adjustment_amount: { amount: number; divisor: number; currency_code: string; }; buyer_total_adjustment_amount: { amount: number; divisor: number; currency_code: string; }; total_fee_adjustment_amount: { amount: number; divisor: number; currency_code: string; }; create_timestamp: number; created_timestamp: number; update_timestamp: number; updated_timestamp: number; } interface EtsyPayment { payment_id: number; buyer_user_id: number; shop_id: number; receipt_id: number; amount_gross: { amount: number; divisor: number; currency_code: string; }; amount_fees: { amount: number; divisor: number; currency_code: string; }; amount_net: { amount: number; divisor: number; currency_code: string; }; posted_gross: { amount: number; divisor: number; currency_code: string; }; posted_fees: { amount: number; divisor: number; currency_code: string; }; posted_net: { amount: number; divisor: number; currency_code: string; }; adjusted_gross: { amount: number; divisor: number; currency_code: string; }; adjusted_fees: { amount: number; divisor: number; currency_code: string; }; adjusted_net: { amount: number; divisor: number; currency_code: string; }; currency: string; shop_currency: string; buyer_currency: string; shipping_user_id?: number; shipping_address_id?: number; billing_address_id: number; status: string; shipped_timestamp?: number; create_timestamp: number; created_timestamp: number; update_timestamp: number; updated_timestamp: number; payment_adjustments?: EtsyPaymentAdjustment[]; } interface GetPaymentAccountLedgerEntriesParams { min_created: number; max_created: number; limit?: number; offset?: number; } interface CreateDraftListingParams { quantity: number; title: string; description: string; price: number; who_made: 'i_did' | 'someone_else' | 'collective'; when_made: typeof ETSY_WHEN_MADE_VALUES[number] | 'made_to_order'; taxonomy_id: number; shipping_profile_id?: number; return_policy_id?: number; materials?: string[]; shop_section_id?: number; processing_min?: number; processing_max?: number; tags?: string[]; styles?: string[]; item_weight?: number; item_length?: number; item_width?: number; item_height?: number; item_weight_unit?: 'oz' | 'lb' | 'g' | 'kg'; item_dimensions_unit?: 'in' | 'ft' | 'mm' | 'cm' | 'm' | 'yd' | 'inches'; is_personalizable?: boolean; personalization_is_required?: boolean; personalization_char_count_max?: number; personalization_instructions?: string; production_partner_ids?: number[]; image_ids?: number[]; readiness_state_id?: number; should_auto_renew?: boolean; is_supply?: boolean; is_customizable?: boolean; is_taxable?: boolean; type?: 'physical' | 'download' | 'both'; } interface UpdateListingParams { image_ids?: number[]; title?: string; description?: string; materials?: string[]; should_auto_renew?: boolean; shipping_profile_id?: number; return_policy_id?: number; shop_section_id?: number; item_weight?: number; item_length?: number; item_width?: number; item_height?: number; item_weight_unit?: 'oz' | 'lb' | 'g' | 'kg'; item_dimensions_unit?: 'in' | 'ft' | 'mm' | 'cm' | 'm' | 'yd' | 'inches'; is_taxable?: boolean; taxonomy_id?: number; tags?: string[]; who_made?: 'i_did' | 'someone_else' | 'collective'; when_made?: typeof ETSY_WHEN_MADE_VALUES[number] | 'made_to_order'; featured_rank?: number; is_personalizable?: boolean; personalization_is_required?: boolean; personalization_char_count_max?: number; personalization_instructions?: string; state?: 'active' | 'inactive'; is_supply?: boolean; production_partner_ids?: number[]; type?: 'physical' | 'download' | 'both'; } interface UpdateListingInventoryParams { products: Array<{ sku?: string; property_values?: Array<{ property_id: number; property_name?: string; scale_id?: number; scale_name?: string; value_ids?: number[]; values?: string[]; }>; offerings: Array<{ offering_id?: number; price: number; quantity: number; is_enabled: boolean; readiness_state_id?: number; }>; }>; price_on_property?: number[]; quantity_on_property?: number[]; sku_on_property?: number[]; readiness_state_on_property?: number[]; } interface EtsyListingProperty { property_id: number; name: string; display_name: string; scales?: EtsyListingPropertyScale[]; possible_values?: EtsyListingPropertyValue[]; selected_values?: EtsyListingPropertyValue[]; supports_attributes?: boolean; supports_variations?: boolean; is_multivalued?: boolean; is_required?: boolean; max_values_allowed?: number; } interface EtsyListingPropertyScale { scale_id: number; display_name: string; description?: string; } interface UpdateListingPropertyParams { shopId: string | number; listingId: string | number; propertyId: number; valueIds: number[]; values: string[]; scaleId?: number; } interface EtsyBuyerTaxonomyNode { id: number; level: number; name: string; parent_id: number | null; children: EtsyBuyerTaxonomyNode[]; full_path_taxonomy_ids: number[]; } interface EtsyBuyerTaxonomyPropertyScale { scale_id: number; display_name: string; description?: string; } interface EtsyBuyerTaxonomyPropertyValue { value_id: number; name: string; scale_id?: number; equal_to?: number[]; } interface EtsyBuyerTaxonomyProperty { property_id: number; name: string; display_name: string; scales?: EtsyBuyerTaxonomyPropertyScale[]; possible_values?: EtsyBuyerTaxonomyPropertyValue[]; selected_values?: EtsyBuyerTaxonomyPropertyValue[]; supports_attributes: boolean; supports_variations: boolean; is_multivalued: boolean; is_required: boolean; max_values_allowed?: number; } interface EtsyShopProductionPartner { production_partner_id: number; partner_name: string; location: string; } interface UploadListingImageParams { image: File | Blob | Buffer; listing_id: number; rank?: number; overwrite?: boolean; is_watermarked?: boolean; alt_text?: string; } interface UploadListingFileParams { file: File | Blob | Buffer; listing_id: number; name?: string; rank?: number; } interface EtsyShopProcessingProfile { shop_id: number; readiness_state_id: number; readiness_state: 'ready_to_ship' | 'made_to_order'; min_processing_days: number; max_processing_days: number; processing_days_display_label: string; } interface CreateReadinessStateParams { readiness_state: 'ready_to_ship' | 'made_to_order'; min_processing_time: number; max_processing_time: number; processing_time_unit?: 'days' | 'weeks'; } interface UpdateReadinessStateParams { readiness_state?: 'ready_to_ship' | 'made_to_order'; min_processing_time?: number; max_processing_time?: number; processing_time_unit?: 'days' | 'weeks'; } interface GetReadinessStateParams { limit?: number; offset?: number; } interface EtsyShopReturnPolicy { return_policy_id: number; shop_id: number; accepts_returns: boolean; accepts_exchanges: boolean; return_deadline: number | null; } interface CreateReturnPolicyParams { accepts_returns: boolean; accepts_exchanges: boolean; return_deadline?: number | null; } interface UpdateReturnPolicyParams { accepts_returns: boolean; accepts_exchanges: boolean; return_deadline?: number | null; } interface ConsolidateReturnPoliciesParams { source_return_policy_id: number; destination_return_policy_id: number; } interface EtsyShopHolidayPreference { shop_id: number; holiday_id: number; country_iso: string; is_working: boolean; holiday_name: string; } interface UpdateHolidayPreferencesParams { is_working: boolean; } interface EtsyListingFile { listing_file_id: number; listing_id: number; rank: number; filename: string; filesize: string; size_bytes: number; filetype: string; create_timestamp: number; created_timestamp: number; } interface EtsyListingVideo { video_id: number; height: number; width: number; thumbnail_url: string; video_url: string; video_state: 'active' | 'inactive' | 'deleted' | 'flagged'; } interface EtsyListingTranslation { listing_id: number; language: string; title: string | null; description: string | null; tags: string[]; } interface CreateListingTranslationParams { title: string; description: string; tags?: string[]; } interface UpdateListingTranslationParams { title: string; description: string; tags?: string[]; } interface EtsyListingVariationImage { property_id: number; value_id: number; value: string | null; image_id: number; } interface UpdateVariationImagesParams { variation_images: Array<{ property_id: number; value_id: number; image_id: number; }>; } interface EtsyUserAddress { user_address_id: number; user_id: number; name: string; first_line: string; second_line: string | null; city: string; state: string | null; zip: string | null; iso_country_code: string | null; country_name: string | null; is_default_shipping_address: boolean; } interface EtsyShippingCarrierMailClass { mail_class_key: string; name: string; } interface EtsyShippingCarrier { shipping_carrier_id: number; name: string; domestic_classes: EtsyShippingCarrierMailClass[]; international_classes: EtsyShippingCarrierMailClass[]; } interface FindShopsParams { shop_name: string; limit?: number; offset?: number; } interface GetListingsByIdsParams { listing_ids: number[]; includes?: ListingIncludes[]; legacy?: boolean; } interface FindActiveListingsByShopParams { limit?: number; offset?: number; sort_on?: 'created' | 'price' | 'updated' | 'score'; sort_order?: 'asc' | 'ascending' | 'desc' | 'descending' | 'up' | 'down'; keywords?: string; legacy?: boolean; } interface GetFeaturedListingsParams { limit?: number; offset?: number; legacy?: boolean; } interface GetListingsByShopReceiptParams { limit?: number; offset?: number; legacy?: boolean; } interface GetListingsBySectionParams { shop_section_ids: number[]; limit?: number; offset?: number; sort_on?: 'created' | 'price' | 'updated' | 'score'; sort_order?: 'asc' | 'ascending' | 'desc' | 'descending' | 'up' | 'down'; legacy?: boolean; } interface GetListingsByReturnPolicyParams { legacy?: boolean; } interface CreateShippingProfileUpgradeParams { type: number; upgrade_name: string; price: number; secondary_price: number; shipping_carrier_id?: number; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; } interface UpdateShippingProfileUpgradeParams { upgrade_name?: string; type?: number; price?: number; secondary_price?: number; shipping_carrier_id?: number; mail_class?: string; min_delivery_days?: number; max_delivery_days?: number; } interface GetTransactionsByListingParams { limit?: number; offset?: number; legacy?: boolean; } interface GetTransactionsByShopParams { limit?: number; offset?: number; legacy?: boolean; } interface GetLedgerEntryPaymentsParams { ledger_entry_ids: number[]; } interface TokenScopesParams { token: string; } interface TokenScopesResponse { scopes: string[]; } interface BulkOperationConfig { concurrency?: number; stopOnError?: boolean; onProgress?: (completed: number, total: number, lastResult?: BulkOperationResult<unknown>) => void; onItemComplete?: (result: BulkOperationResult<unknown>) => void; onItemError?: (error: BulkOperationError) => void; } interface BulkOperationResult<T> { success: boolean; data?: T; error?: Error; id: string | number; index: number; } interface BulkOperationError { id: string | number; index: number; error: Error; } interface BulkUpdateListingOperation { listingId: string | number; updates: UpdateListingParams; } interface BulkImageUploadOperation { file: Blob | Buffer | string; rank: number; altText?: string; } interface BulkOperationSummary<T> { total: number; successful: number; failed: number; results: BulkOperationResult<T>[]; errors: BulkOperationError[]; duration: number; } declare class BulkOperationManager { private concurrency; private stopOnError; private onProgress?; private onItemComplete?; private onItemError?; constructor(config?: BulkOperationConfig); executeBulk<TInput, TOutput>(items: TInput[], operation: (item: TInput, index: number) => Promise<TOutput>, getId?: (item: TInput, index: number) => string | number): Promise<BulkOperationSummary<TOutput>>; private worker; setConcurrency(concurrency: number): void; getConcurrency(): number; } declare function createBulkOperationManager(config?: BulkOperationConfig): BulkOperationManager; declare function executeBulkOperation<TInput, TOutput>(items: TInput[], operation: (item: TInput, index: number) => Promise<TOutput>, config?: BulkOperationConfig): Promise<BulkOperationSummary<TOutput>>; interface ValidationResult { valid: boolean; errors: ValidationError[]; } interface ValidationError { field: string; message: string; value?: unknown; } interface ValidationSchema<T = unknown> { validate(data: T): ValidationResult; } interface ValidatorFunction<T = unknown> { (data: T): ValidationResult; } declare class Validator<T = unknown> implements ValidationSchema<T> { private validators; rule(validator: (data: T) => ValidationError | null): this; validate(data: T): ValidationResult; } declare class FieldValidator { private field; constructor(field: string); required(message?: string): (data: unknown) => ValidationError | null; string(options: { min?: number; max?: number; pattern?: RegExp; message?: string; }): (data: unknown) => ValidationError | null; number(options: { min?: number; max?: number; integer?: boolean; positive?: boolean; message?: string; }): (data: unknown) => ValidationError | null; enum<T>(allowedValues: T[], message?: string): (data: unknown) => ValidationError | null; array(options: { min?: number; max?: number; itemValidator?: (item: unknown) => boolean; message?: string; }): (data: unknown) => ValidationError | null; } declare function field(fieldName: string): FieldValidator; declare const CreateListingSchema: Validator<CreateDraftListingParams>; declare const UpdateListingSchema: Validator<UpdateListingParams>; declare const UpdateShopSchema: Validator<unknown>; interface ValidationOptions { validate?: boolean; validateSchema?: ValidationSchema; throwOnValidationError?: boolean; validateResponse?: boolean; } declare class ValidationException extends Error { errors: ValidationError[]; constructor(message: string, errors: ValidationError[]); } declare function validateOrThrow<T>(data: T, schema: ValidationSchema<T>, errorMessage?: string): void; declare function validate<T>(data: T, schema: ValidationSchema<T>): ValidationResult; declare function createValidator<T>(): Validator<T>; declare function combineValidators<T>(...validators: ValidationSchema<T>[]): ValidationSchema<T>; declare class EtsyClient { private tokenManager; private rateLimiter; private baseUrl; private logger; private cache?; private cacheTtl; private keystring; private sharedSecret; private bulkOperationManager; constructor(config: EtsyClientConfig); private makeRequest; private executeWithRetry; private sleep; private buildFormBody; private getApiKey; getUser(): Promise<EtsyUser>; getShop(shopId?: string): Promise<EtsyShop>; getShopByOwnerUserId(userId: string): Promise<EtsyShop>; getShopSections(shopId?: string): Promise<EtsyShopSection[]>; getShopSection(shopId: string, sectionId: string): Promise<EtsyShopSection>; getListingsByShop(shopId?: string, params?: ListingParams): Promise<EtsyListing[]>; getListing(listingId: string, params?: GetListingParams | ListingIncludes[]): Promise<EtsyListing>; findAllListingsActive(params?: SearchParams): Promise<EtsyListing[]>; getListingImages(listingId: string): Promise<EtsyListingImage[]>; getListingInventory(listingId: string, params?: GetListingInventoryParams): Promise<EtsyListingInventory>; getReviewsByListing(listingId: string, params?: GetReviewsParams): Promise<EtsyReview[]>; getReviewsByShop(shopId: string, params?: GetReviewsParams): Promise<EtsyReview[]>; getSellerTaxonomyNodes(): Promise<EtsySellerTaxonomyNode[]>; getUserShops(): Promise<EtsyShop[]>; updateShop(shopId: string, params: UpdateShopParams, options?: ValidationOptions): Promise<EtsyShop>; createShopSection(shopId: string, params: CreateShopSectionParams): Promise<EtsyShopSection>; updateShopSection(shopId: string, sectionId: string, params: UpdateShopSectionParams): Promise<EtsyShopSection>; deleteShopSection(shopId: string, sectionId: string): Promise<void>; createDraftListing(shopId: string, params: CreateDraftListingParams, options?: ValidationOptions & { legacy?: boolean; }): Promise<EtsyListing>; updateListing(shopId: string, listingId: string, params: UpdateListingParams, options?: ValidationOptions & { legacy?: boolean; }): Promise<EtsyListing>; deleteListing(listingId: string): Promise<void>; updateListingInventory(listingId: string, params: UpdateListingInventoryParams, options?: { legacy?: boolean; }): Promise<EtsyListingInventory>; uploadListingImage(shopId: string, listingId: string, imageData: Blob | Buffer, params?: { rank?: number; overwrite?: boolean; is_watermarked?: boolean; alt_text?: string; }): Promise<EtsyListingImage>; getListingImage(listingId: string, imageId: string): Promise<EtsyListingImage>; deleteListingImage(shopId: string, listingId: string, imageId: string): Promise<void>; bulkUpdateListings(shopId: string, operations: BulkUpdateListingOperation[], config?: BulkOperationConfig): Promise<BulkOperationSummary<EtsyListing>>; bulkUploadImages(shopId: string, listingId: string, images: BulkImageUploadOperation[], config?: BulkOperationConfig): Promise<BulkOperationSummary<EtsyListingImage>>; setBulkOperationConcurrency(concurrency: number): void; getShopReceipts(shopId: string, params?: GetShopReceiptsParams): Promise<EtsyShopReceipt[]>; getShopReceipt(shopId: string, receiptId: string, params?: GetShopReceiptParams): Promise<EtsyShopReceipt>; updateShopReceipt(shopId: string, receiptId: string, params: UpdateShopReceiptParams, options?: { legacy?: boolean; }): Promise<EtsyShopReceipt>; getShopReceiptTransactions(shopId: string, receiptId: string, params?: GetShopReceiptTransactionsParams): Promise<EtsyShopReceiptTransaction[]>; getShopTransaction(shopId: string, transactionId: string): Promise<EtsyShopReceiptTransaction>; getShopShippingProfiles(shopId: string): Promise<EtsyShippingProfile[]>; createShopShippingProfile(shopId: string, params: CreateShippingProfileParams): Promise<EtsyShippingProfile>; getShopShippingProfile(shopId: string, profileId: string): Promise<EtsyShippingProfile>; updateShopShippingProfile(shopId: string, profileId: string, params: UpdateShippingProfileParams): Promise<EtsyShippingProfile>; deleteShopShippingProfile(shopId: string, profileId: string): Promise<void>; getShopShippingProfileDestinations(shopId: string, profileId: string, params?: GetShippingProfileDestinationsParams): Promise<EtsyShippingProfileDestination[]>; createShopShippingProfileDestination(shopId: string, profileId: string, params: CreateShippingProfileDestinationParams): Promise<EtsyShippingProfileDestination>; updateShopShippingProfileDestination(shopId: string, profileId: string, destinationId: string, params: UpdateShippingProfileDestinationParams): Promise<EtsyShippingProfileDestination>; deleteShopShippingProfileDestination(shopId: string, profileId: string, destinationId: string): Promise<void>; getShopShippingProfileUpgrades(shopId: string, profileId: string): Promise<EtsyShippingProfileUpgrade[]>; createReceiptShipment(shopId: string, receiptId: string, params: CreateReceiptShipmentParams, options?: { legacy?: boolean; }): Promise<EtsyShopReceiptShipment>; getShopPaymentAccountLedgerEntries(shopId: string, params: GetPaymentAccountLedgerEntriesParams): Promise<EtsyPaymentAccountLedgerEntry[]>; getShopPaymentAccountLedgerEntry(shopId: string, entryId: string): Promise<EtsyPaymentAccountLedgerEntry>; getPayments(shopId: string, paymentIds: number[]): Promise<EtsyPayment[]>; getShopPayment(shopId: string, paymentId: string): Promise<EtsyPayment>; getBuyerTaxonomyNodes(): Promise<EtsyBuyerTaxonomyNode[]>; getPropertiesByTaxonomyId(taxonomyId: number): Promise<EtsyBuyerTaxonomyProperty[]>; getListingProperties(shopId: string, listingId: string): Promise<EtsyListingProperty[]>; updateListingProperty(params: UpdateListingPropertyParams): Promise<EtsyListingProperty>; getShopProductionPartners(shopId: string): Promise<EtsyShopProductionPartner[]>; createShopReadinessStateDefinition(shopId: string, params: CreateReadinessStateParams): Promise<EtsyShopProcessingProfile>; getShopReadinessStateDefinitions(shopId: string, params?: GetReadinessStateParams): Promise<EtsyShopProcessingProfile[]>; getShopReadinessStateDefinition(shopId: string, definitionId: string): Promise<EtsyShopProcessingProfile>; updateShopReadinessStateDefinition(shopId: string, definitionId: string, params: UpdateReadinessStateParams): Promise<EtsyShopProcessingProfile>; deleteShopReadinessStateDefinition(shopId: string, definitionId: string): Promise<void>; createShopReturnPolicy(shopId: string, params: CreateReturnPolicyParams): Promise<EtsyShopReturnPolicy>; getShopReturnPolicies(shopId: string): Promise<EtsyShopReturnPolicy[]>; getShopReturnPolicy(shopId: string, returnPolicyId: string): Promise<EtsyShopReturnPolicy>; updateShopReturnPolicy(shopId: string, returnPolicyId: string, params: UpdateReturnPolicyParams): Promise<EtsyShopReturnPolicy>; deleteShopReturnPolicy(shopId: string, returnPolicyId: string): Promise<void>; consolidateShopReturnPolicies(shopId: string, params: ConsolidateReturnPoliciesParams): Promise<EtsyShopReturnPolicy>; getHolidayPreferences(shopId: string): Promise<EtsyShopHolidayPreference[]>; updateHolidayPreferences(shopId: string, holidayId: string, params: UpdateHolidayPreferencesParams): Promise<EtsyShopHolidayPreference>; uploadListingFile(shopId: string, listingId: string, fileData: Blob | Buffer, params?: { name?: string; rank?: number; listing_file_id?: number; }): Promise<EtsyListingFile>; getAllListingFiles(shopId: string, listingId: string): Promise<EtsyListingFile[]>; getListingFile(shopId: string, listingId: string, fileId: string): Promise<EtsyListingFile>; deleteListingFile(shopId: string, listingId: string, fileId: string): Promise<void>; uploadListingVideo(shopId: string, listingId: string, videoData: Blob | Buffer, params?: { name?: string; video_id?: number; }): Promise<EtsyListingVideo>; getListingVideos(listingId: string): Promise<EtsyListingVideo[]>; getListingVideo(listingId: string, videoId: string): Promise<EtsyListingVideo>; deleteListingVideo(shopId: string, listingId: string, videoId: string): Promise<void>; getListingPersonalizations(listingId: string): Promise<EtsyListingPersonalization>; updateListingPersonalization(shopId: string, listingId: string, params: UpdatePersonalizationParams): Promise<EtsyListingPersonalization>; deleteListingPersonalization(shopId: string, listingId: string): Promise<void>; createListingTranslation(shopId: string, listingId: string, language: string, params: CreateListingTranslationParams): Promise<EtsyListingTranslation>; getListingTranslation(shopId: string, listingId: string, language: string): Promise<EtsyListingTranslation>; updateListingTranslation(shopId: string, listingId: string, language: string, params: UpdateListingTranslationParams): Promise<EtsyListingTranslation>; getListingVariationImages(shopId: string, listingId: string): Promise<EtsyListingVariationImage[]>; updateVariationImages(shopId: string, listingId: string, params: UpdateVariationImagesParams): Promise<EtsyListingVariationImage[]>; findAllActiveListingsByShop(shopId: string, params?: FindActiveListingsByShopParams): Promise<EtsyListing[]>; getFeaturedListingsByShop(shopId: string, params?: GetFeaturedListingsParams): Promise<EtsyListing[]>; getListingsByListingIds(params: GetListingsByIdsParams): Promise<EtsyListing[]>; getListingsByShopReceipt(shopId: string, receiptId: string, params?: GetListingsByShopReceiptParams): Promise<EtsyListing[]>; getListingProperty(listingId: string, propertyId: string): Promise<EtsyListingProperty>; deleteListingProperty(shopId: string, listingId: string, propertyId: string): Promise<void>; getListingProduct(listingId: string, productId: string): Promise<EtsyListingProduct>; getListingOffering(listingId: string, productId: string, offeringId: string): Promise<EtsyListingOffering>; getListingsByShopSectionId(shopId: string, params: GetListingsBySectionParams): Promise<EtsyListing[]>; getListingsByShopReturnPolicy(shopId: string, returnPolicyId: string, params?: GetListingsByReturnPolicyParams): Promise<EtsyListing[]>; findShops(params: FindShopsParams): Promise<EtsyShop[]>; createShopShippingProfileUpgrade(shopId: string, profileId: string, params: CreateShippingProfileUpgradeParams): Promise<EtsyShippingProfileUpgrade>; updateShopShippingProfileUpgrade(shopId: string, profileId: string, upgradeId: string, params: UpdateShippingProfileUpgradeParams): Promise<EtsyShippingProfileUpgrade>; deleteShopShippingProfileUpgrade(shopId: string, profileId: string, upgradeId: string): Promise<void>; getShippingCarriers(originCountryIso: string): Promise<EtsyShippingCarrier[]>; getShopReceiptTransactionsByListing(shopId: string, listingId: string, params?: GetTransactionsByListingParams): Promise<EtsyShopReceiptTransaction[]>; getShopReceiptTransactionsByShop(shopId: string, params?: GetTransactionsByShopParams): Promise<EtsyShopReceiptTransaction[]>; getPaymentAccountLedgerEntryPayments(shopId: string, params: GetLedgerEntryPaymentsParams): Promise<EtsyPayment[]>; getShopPaymentByReceiptId(shopId: string, receiptId: string): Promise<EtsyPayment[]>; getMe(): Promise<EtsyUser>; getUserAddresses(): Promise<EtsyUserAddress[]>; getUserAddress(userAddressId: string): Promise<EtsyUserAddress>; deleteUserAddress(userAddressId: string): Promise<void>; getPropertiesByBuyerTaxonomyId(taxonomyId: number): Promise<EtsyBuyerTaxonomyProperty[]>; ping(): Promise<number>; tokenScopes(params: TokenScopesParams): Promise<TokenScopesResponse>; getRemainingRequests(): number; getRateLimitStatus(): RateLimitStatus; onApproachingRateLimit(callback: ApproachingLimitCallback, threshold?: number): void; clearCache(): Promise<void>; getCurrentTokens(): EtsyTokens | null; isTokenExpired(): boolean; refreshToken(): Promise<EtsyTokens>; private fetch; } declare class AuthHelper { private readonly keystring; private readonly redirectUri; private readonly scopes; private codeVerifier; private state; private authorizationCode?; private receivedState?; private initialized; constructor(config: AuthHelperConfig); private initialize; getAuthUrl(): Promise<string>; setAuthorizationCode(code: s