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

package/dist/index.d.ts

@@ -39,14 +39,28 @@ interface EtsyTokenResponse {
     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;
@@ -233,6 +247,14 @@ interface EtsyListingPropertyValue {
     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;
@@ -264,12 +286,25 @@ interface RateLimitStatus {
     resetTime: Date;
     canMakeRequest: boolean;
 }
+interface EtsyErrorDetails {
+    statusCode: number;
+    errorCode?: string;
+    field?: string;
+    suggestion?: string;
+    retryAfter?: number;
+}
 declare class EtsyApiError extends Error {
     _statusCode?: number | undefined;
     _response?: unknown | undefined;
-    constructor(message: string, _statusCode?: number | undefined, _response?: unknown | undefined);
+    _retryAfter?: number | undefined;
+    details: EtsyErrorDetails;
+    constructor(message: string, _statusCode?: number | undefined, _response?: unknown | undefined, _retryAfter?: number | undefined);
     get statusCode(): number | undefined;
     get response(): unknown | undefined;
+    isRetryable(): boolean;
+    getRetryAfter(): number | null;
+    getRateLimitReset(): Date | null;
+    getUserFriendlyMessage(): string;
 }
 declare class EtsyAuthError extends Error {
     _code?: string | undefined;
@@ -293,6 +328,676 @@ interface LoggerInterface {
     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;
+}
+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' | 'paid';
+    sort_order?: '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;
+}
+interface UpdateShopReceiptParams {
+    was_shipped?: boolean;
+    was_paid?: boolean;
+    message_from_seller?: string;
+}
+interface EtsyShippingProfile {
+    shipping_profile_id: number;
+    title: string;
+    user_id: number;
+    min_processing_days: number;
+    max_processing_days: number;
+    processing_days_display_label: string;
+    origin_country_iso: string;
+    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_days: number;
+    max_processing_days: number;
+    processing_days_display_label?: string;
+    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_days?: number;
+    max_processing_days?: number;
+    processing_days_display_label?: 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;
+}
+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;
+}
+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[];
+    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' | 'draft';
+    is_supply?: boolean;
+    production_partner_ids?: number[];
+    type?: 'physical' | 'download' | 'both';
+    styles?: string[];
+    processing_min?: number;
+    processing_max?: number;
+}
+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;
+        }>;
+    }>;
+    price_on_property?: number[];
+    quantity_on_property?: number[];
+    sku_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 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 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;
@@ -302,6 +1007,7 @@ declare class EtsyClient {
     private cache?;
     private cacheTtl;
     private keystring;
+    private bulkOperationManager;
     constructor(config: EtsyClientConfig);
     private makeRequest;
     private getApiKey;
@@ -315,6 +1021,51 @@ declare class EtsyClient {
     findAllListingsActive(params?: SearchParams): Promise<EtsyListing[]>;
     getListingImages(listingId: string): Promise<EtsyListingImage[]>;
     getListingInventory(listingId: string): Promise<EtsyListingInventory>;
+    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): Promise<EtsyListing>;
+    updateListing(shopId: string, listingId: string, params: UpdateListingParams, options?: ValidationOptions): Promise<EtsyListing>;
+    deleteListing(listingId: string): Promise<void>;
+    updateListingInventory(listingId: string, params: UpdateListingInventoryParams): Promise<EtsyListingInventory>;
+    uploadListingImage(shopId: string, listingId: string, imageData: Blob | Buffer, params?: {
+        rank?: number;
+        overwrite?: boolean;
+        is_watermarked?: boolean;
+        alt_text?: string;
+    }): Promise<EtsyListingImage>;
+    getListingImage(shopId: string, 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): Promise<EtsyShopReceipt>;
+    updateShopReceipt(shopId: string, receiptId: string, params: UpdateShopReceiptParams): Promise<EtsyShopReceipt>;
+    getShopReceiptTransactions(shopId: string, receiptId: string): 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): 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): Promise<EtsyShopReceiptShipment>;
+    getShopReceiptShipments(shopId: string, receiptId: string): Promise<EtsyShopReceiptShipment[]>;
+    getShopPaymentAccountLedgerEntries(shopId: string, params: GetPaymentAccountLedgerEntriesParams): Promise<EtsyPaymentAccountLedgerEntry[]>;
+    getShopPaymentAccountLedgerEntry(shopId: string, entryId: string): Promise<EtsyPaymentAccountLedgerEntry>;
+    getShopPayment(shopId: string, paymentId: string): Promise<EtsyPayment>;
+    getBuyerTaxonomyNodes(): Promise<EtsyBuyerTaxonomyNode[]>;
+    getPropertiesByTaxonomyId(taxonomyId: number): Promise<EtsyBuyerTaxonomyProperty[]>;
+    getListingProperties(shopId: string, listingId: string): Promise<EtsyListingProperty[]>;
+    getShopProductionPartners(shopId: string): Promise<EtsyShopProductionPartner[]>;
     getRemainingRequests(): number;
     getRateLimitStatus(): RateLimitStatus;
     clearCache(): Promise<void>;
@@ -391,7 +1142,9 @@ declare class TokenManager {
     private refreshCallback?;
     private storage?;
     private refreshPromise?;
-    constructor(config: EtsyClientConfig, storage?: TokenStorage);
+    private rotationConfig?;
+    private rotationTimer?;
+    constructor(config: EtsyClientConfig, storage?: TokenStorage, rotationConfig?: TokenRotationConfig);
     getAccessToken(): Promise<string>;
     refreshToken(): Promise<EtsyTokens>;
     private performTokenRefresh;
@@ -401,6 +1154,12 @@ declare class TokenManager {
     willTokenExpireSoon(minutes?: number): boolean;
     clearTokens(): Promise<void>;
     getTimeUntilExpiration(): number | null;
+    needsProactiveRotation(): boolean;
+    rotateToken(): Promise<EtsyTokens>;
+    startRotationScheduler(): void;
+    stopRotationScheduler(): void;
+    updateRotationConfig(config: TokenRotationConfig): void;
+    getRotationConfig(): TokenRotationConfig | undefined;
     private fetch;
 }
 declare function createDefaultTokenStorage(options?: {
@@ -429,6 +1188,7 @@ declare class FileTokenStorage implements TokenStorage {
     load(): Promise<EtsyTokens | null>;
     clear(): Promise<void>;
     private _writeFile;
+    private _setFilePermissions;
     private _readFile;
     private _deleteFile;
 }
@@ -450,6 +1210,312 @@ declare class EtsyRateLimiter {
 }
 declare const defaultRateLimiter: EtsyRateLimiter;
 
+interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+    maxPages?: number;
+    maxItems?: number;
+}
+type PageFetcher<T> = (limit: number, offset: number) => Promise<EtsyApiResponse<T>>;
+declare class PaginatedResults<T> implements AsyncIterable<T> {
+    private fetcher;
+    private options;
+    private currentPage;
+    private currentOffset;
+    private totalCount;
+    private hasMore;
+    constructor(fetcher: PageFetcher<T>, options?: PaginationOptions);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    getAll(): Promise<T[]>;
+    getCurrentPage(): T[];
+    hasNextPage(): boolean;
+    getNextPage(): Promise<T[]>;
+    getTotalCount(): number | null;
+    reset(): void;
+    private fetchPage;
+}
+declare function createPaginatedResults<T>(fetcher: PageFetcher<T>, options?: PaginationOptions): PaginatedResults<T>;
+
+interface RetryConfig {
+    maxRetries: number;
+    retryDelay: number;
+    exponentialBackoff: boolean;
+    retryableStatusCodes: number[];
+    onRetry?: (attempt: number, error: Error) => void;
+    maxRetryDelay?: number;
+    jitter?: number;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+interface RetryOptions extends Partial<RetryConfig> {
+    signal?: AbortSignal;
+}
+declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+declare class RetryManager {
+    private config;
+    constructor(config?: Partial<RetryConfig>);
+    execute<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    updateConfig(config: Partial<RetryConfig>): void;
+    getConfig(): RetryConfig;
+}
+
+interface WebhookConfig {
+    secret: string;
+    algorithm?: 'sha256' | 'sha1';
+    verifySignatures?: boolean;
+}
+type EtsyWebhookEventType = 'receipt.updated' | 'receipt.created' | 'listing.updated' | 'listing.created' | 'listing.deactivated' | 'shop.updated';
+interface EtsyWebhookEvent {
+    type: EtsyWebhookEventType;
+    timestamp: number;
+    data: EtsyShopReceipt | EtsyListing | unknown;
+    shop_id?: number;
+    user_id?: number;
+}
+type WebhookEventHandler<T = unknown> = (data: T) => void | Promise<void>;
+declare class EtsyWebhookHandler {
+    private config;
+    private handlers;
+    private crypto;
+    constructor(config: WebhookConfig);
+    verifySignature(payload: string, signature: string): boolean;
+    parseEvent(payload: string | object): EtsyWebhookEvent;
+    on<T = unknown>(eventType: EtsyWebhookEventType, handler: WebhookEventHandler<T>): void;
+    off(eventType: EtsyWebhookEventType, handler: WebhookEventHandler): void;
+    removeAllListeners(eventType?: EtsyWebhookEventType): void;
+    private triggerHandlers;
+    private timingSafeEqual;
+    getHandlerCount(eventType: EtsyWebhookEventType): number;
+    getRegisteredEventTypes(): EtsyWebhookEventType[];
+}
+declare function createWebhookHandler(config: WebhookConfig): EtsyWebhookHandler;
+
+type CacheStrategy = 'lru' | 'lfu' | 'ttl' | 'custom';
+interface AdvancedCachingConfig {
+    strategy?: CacheStrategy;
+    ttl?: number;
+    maxSize?: number;
+    maxEntries?: number;
+    invalidateOn?: {
+        mutations?: boolean;
+        patterns?: string[];
+    };
+    trackStats?: boolean;
+}
+interface CacheEntry {
+    key: string;
+    value: string;
+    expires: number;
+    size: number;
+    accessCount: number;
+    lastAccessed: number;
+    created: number;
+}
+interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    missRate: number;
+    size: number;
+    entryCount: number;
+    evictions: number;
+    maxSize: number;
+    maxEntries: number;
+}
+declare class LRUCache implements CacheStorage {
+    private cache;
+    private maxSize;
+    private maxEntries;
+    private ttl;
+    private currentSize;
+    private stats;
+    private trackStats;
+    constructor(config?: AdvancedCachingConfig);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    private evictLRU;
+    private estimateSize;
+    getStats(): CacheStats;
+}
+declare class LFUCache implements CacheStorage {
+    private cache;
+    private maxSize;
+    private maxEntries;
+    private ttl;
+    private currentSize;
+    private stats;
+    private trackStats;
+    constructor(config?: AdvancedCachingConfig);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    private evictLFU;
+    private estimateSize;
+    getStats(): CacheStats;
+}
+declare class CacheWithInvalidation implements CacheStorage {
+    private baseCache;
+    private invalidationPatterns;
+    private mutationPatterns;
+    constructor(baseCache: CacheStorage, config?: AdvancedCachingConfig);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    invalidatePattern(_pattern: string): Promise<void>;
+    invalidateOnMutation(mutationType: string): Promise<void>;
+    addInvalidationPattern(pattern: string): void;
+    removeInvalidationPattern(pattern: string): void;
+    addMutationPattern(mutationType: string, patterns: string[]): void;
+}
+interface RedisConfig {
+    host: string;
+    port: number;
+    password?: string;
+    db?: number;
+    keyPrefix?: string;
+}
+interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    setex(key: string, ttl: number, value: string): Promise<void>;
+    del(...keys: string[]): Promise<void>;
+    keys(pattern: string): Promise<string[]>;
+}
+declare class RedisCacheStorage implements CacheStorage {
+    private config;
+    private client;
+    private keyPrefix;
+    constructor(config: RedisConfig, client: RedisClientLike);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getClient(): RedisClientLike;
+}
+declare function createCacheStorage(config?: AdvancedCachingConfig): CacheStorage;
+declare function createCacheWithInvalidation(baseCache: CacheStorage, config?: AdvancedCachingConfig): CacheWithInvalidation;
+declare function createRedisCacheStorage(config: RedisConfig, client: RedisClientLike): RedisCacheStorage;
+
+type SortOrder = 'asc' | 'desc';
+type ListingState = 'active' | 'inactive' | 'draft' | 'expired';
+type ListingSortOn = 'created' | 'price' | 'updated' | 'score';
+declare class ListingQueryBuilder {
+    private client;
+    private shopId?;
+    private params;
+    private includeFields;
+    constructor(client: EtsyClient, shopId?: string);
+    where(filters: {
+        state?: ListingState;
+        shop_section_id?: number;
+    }): this;
+    include(fields: string[]): this;
+    limit(limit: number): this;
+    offset(offset: number): this;
+    sortBy(field: ListingSortOn, order?: SortOrder): this;
+    fetch(): Promise<EtsyListing[]>;
+    first(): Promise<EtsyListing | null>;
+    count(): Promise<number>;
+}
+declare class ReceiptQueryBuilder {
+    private client;
+    private shopId;
+    private params;
+    constructor(client: EtsyClient, shopId: string);
+    where(filters: {
+        was_paid?: boolean;
+        was_shipped?: boolean;
+        was_delivered?: boolean;
+        min_created?: number;
+        max_created?: number;
+    }): this;
+    limit(limit: number): this;
+    offset(offset: number): this;
+    sortBy(field: 'created' | 'updated', order?: SortOrder): this;
+    fetch(): Promise<EtsyShopReceipt[]>;
+    first(): Promise<EtsyShopReceipt | null>;
+}
+declare class BatchQueryExecutor {
+    private client;
+    private operations;
+    constructor(client: EtsyClient);
+    getShop(shopId: string): this;
+    getListings(shopId: string, params?: ListingParams): this;
+    getReceipts(shopId: string, params?: GetShopReceiptsParams): this;
+    custom<T>(operation: () => Promise<T>): this;
+    execute(): Promise<unknown[]>;
+    executeSequential(): Promise<unknown[]>;
+    clear(): this;
+    size(): number;
+}
+interface EtsyClientWithQueryBuilder extends EtsyClient {
+    listings(shopId?: string): ListingQueryBuilder;
+    receipts(shopId: string): ReceiptQueryBuilder;
+    batch(): BatchQueryExecutor;
+}
+declare function withQueryBuilder(client: EtsyClient): EtsyClientWithQueryBuilder;
+declare function createListingQuery(client: EtsyClient, shopId?: string): ListingQueryBuilder;
+declare function createReceiptQuery(client: EtsyClient, shopId: string): ReceiptQueryBuilder;
+declare function createBatchQuery(client: EtsyClient): BatchQueryExecutor;
+
+interface EncryptedData {
+    ciphertext: string;
+    iv: string;
+    authTag: string;
+    algorithm: string;
+}
+declare function encryptAES256GCM(data: string, key: Buffer | string): Promise<EncryptedData>;
+declare function decryptAES256GCM(encryptedData: EncryptedData, key: Buffer | string): Promise<string>;
+declare function generateEncryptionKey(length?: number): Promise<Buffer>;
+declare function deriveKeyFromPassword(password: string, salt: Buffer | string, iterations?: number, keyLength?: number): Promise<Buffer>;
+declare function validateEncryptionKey(key: Buffer | string, requiredLength?: number): boolean;
+
+interface EncryptedStorageConfig {
+    filePath: string;
+    encryptionKey: string | Buffer;
+    fileMode?: number;
+}
+declare class EncryptedFileTokenStorage implements TokenStorage {
+    private filePath;
+    private encryptionKey;
+    private fileMode;
+    constructor(config: EncryptedStorageConfig);
+    save(tokens: EtsyTokens): Promise<void>;
+    load(): Promise<EtsyTokens | null>;
+    clear(): Promise<void>;
+    getFilePath(): string;
+    exists(): Promise<boolean>;
+    private _writeFile;
+    private _setFilePermissions;
+    private _readFile;
+    private _deleteFile;
+    private _stat;
+}
+
+interface WebhookSecurityConfig {
+    secret: string;
+    algorithm?: 'sha256' | 'sha1' | 'sha512';
+}
+declare class WebhookSecurity {
+    private secret;
+    private algorithm;
+    private crypto;
+    constructor(config: WebhookSecurityConfig);
+    signRequest(payload: string | object, encoding?: 'hex' | 'base64'): string;
+    verifySignature(payload: string | object, signature: string, encoding?: 'hex' | 'base64'): boolean;
+    signRequestWithTimestamp(payload: string | object, timestamp?: number, encoding?: 'hex' | 'base64'): {
+        timestamp: number;
+        signature: string;
+    };
+    verifySignatureWithTimestamp(payload: string | object, signature: string, timestamp: number, maxAge?: number, encoding?: 'hex' | 'base64'): boolean;
+    private timingSafeEqual;
+    getAlgorithm(): string;
+    updateSecret(newSecret: string): void;
+}
+declare function createWebhookSecurity(secret: string, algorithm?: 'sha256' | 'sha1' | 'sha512'): WebhookSecurity;
+
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 declare const hasLocalStorage: boolean;
@@ -479,7 +1545,7 @@ declare function createAuthHelper(config: AuthHelperConfig): AuthHelper;
 declare function createTokenManager(config: EtsyClientConfig, storage?: TokenStorage): TokenManager;
 declare function createRateLimiter(config?: Partial<RateLimitConfig>): EtsyRateLimiter;
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "2.2.0";
 declare const LIBRARY_NAME = "etsy-v3-api-client";
 declare function getLibraryInfo(): {
     name: string;
@@ -490,5 +1556,5 @@ declare function getLibraryInfo(): {
     homepage: string;
 };
 
-export { AuthHelper, COMMON_SCOPE_COMBINATIONS, ETSY_SCOPES, EtsyApiError, EtsyAuthError, EtsyClient, EtsyRateLimitError, EtsyRateLimiter, FileTokenStorage, LIBRARY_NAME, LocalStorageTokenStorage, MemoryTokenStorage, SessionStorageTokenStorage, TokenManager, VERSION, createAuthHelper, createCodeChallenge, createDefaultTokenStorage, createEtsyClient, createRateLimiter, createTokenManager, EtsyClient as default, defaultRateLimiter, generateCodeVerifier, generateRandomBase64Url, generateState, getAvailableStorage, getEnvironmentInfo, getLibraryInfo, hasLocalStorage, hasSessionStorage, isBrowser, isNode, sha256, sha256Base64Url };
-export type { AuthHelperConfig, CacheStorage, EtsyApiResponse, EtsyClientConfig, EtsyListing, EtsyListingImage, EtsyListingInventory, EtsyListingOffering, EtsyListingProduct, EtsyListingPropertyValue, EtsyShop, EtsyShopSection, EtsyTokenResponse, EtsyTokens, EtsyUser, ListingParams, LoggerInterface, RateLimitConfig, RateLimitStatus, SearchParams, TokenRefreshCallback, TokenStorage };
+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 };