peddler 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 747dd42d445c711adc43f20e6a9c479bf795352512fecc67814f1a5f698c86a9
-  data.tar.gz: 134255293900b9c32086f2291a42498e1477f29df64cbe0aa8b3da1420dfe320
+  metadata.gz: dbfcab3cd9afbb211acda145066e991a077d4b771faafe7a6c64dc57d46056bf
+  data.tar.gz: d479659f5bbc4b3787575503d3d2953fab17d193c86604da906b594295e74e5f
 SHA512:
-  metadata.gz: 5880a513c77e79ae8523ca96c69d65697c179ede0febc18f2b4a10d932e7de9ed32cdf74c82ff13bc68ca7c15ae6df9d84ec92150d7bc018da6778e104dcb889
-  data.tar.gz: 60b00292980fdac6da6acccac237b0ce677f7e49cb001f72584426aa70d54deac3c84d9e89abc5e380cf94aecda6db0d695d39868644380acb8c86603245e30d
+  metadata.gz: a80fe622c0c2a81045b7d9e96b98f5bbc7b265ba646f2ecac3f6121e35ec6d138dcd039b8630a52be64ae9c4d9547cb1bdc00cf0c9e11fff1e03581d185314f0
+  data.tar.gz: 7385d0a49ec8c5f714efd95d355b6cfec21924cdfc860ceec144ec615b476393ac5b0455bb47f0fe4e583b24f00686aeddd87b5742261d4cf8e417818926a2f6

data/README.md

@@ -4,7 +4,7 @@
 
 **Peddler** is a Ruby interface to the [Amazon Selling Partner API (SP-API)][docs-overview]. The SP-API enables Amazon sellers and vendors to programmatically access their data on orders, shipments, payments, and more.
 
-Peddler is automatically generated from the Open API models provided by Amazon.
+Peddler is automatically generated from the latest Open API models provided by Amazon.
 
 To begin using the Amazon SP-API, you must [register as a developer][register-as-developer] and [register your application][register-application]. Once registered, [obtain your Login with Amazon (LWA) credentials][view-credentials] to access your own or other selling partners' data.
 
@@ -27,6 +27,16 @@ And then execute:
 bundle install
 ```
 
+### Optional Dependencies
+
+For enhanced error handling when uploading or downloading files, Peddler can parse XML error responses from Amazon S3 if Nokogiri is available:
+
+```ruby
+gem "nokogiri"
+```
+
+If Nokogiri is not available, S3 XML errors will still be handled gracefully, but with less detailed error information.
+
 ## Usage
 
 Set your LWA credentials in your environment.
@@ -102,8 +112,6 @@ Amazon's SP-API imposes [rate limits][rate-limits] on operations. Override the d
 
 Provide an optional `:retries` argument when initializing an API to specify retry attempts if throttled. Default is 0 (no retries). If set to a positive value, Peddler will retry with exponential backoff based on the rate limit.
 
-**Note:** This functionality requires version 6 of the [HTTP library][httprb], which is not yet released. To use rate limiting, point to their main branch on GitHub.
-
 ```ruby
 api = Peddler.orders_v0(aws_region, access_token, retries: 3)
 api.get_orders(
@@ -112,6 +120,87 @@ api.get_orders(
 )
 ```
 
+### Error Handling
+
+By default, Peddler v4 maintains backward compatibility:
+- **Client errors (4xx)**: Always raise `Peddler::Error` exceptions
+- **Server errors (5xx)**: Return response objects (deprecated behavior)
+
+To adopt the recommended v5.0 behavior where all errors raise exceptions:
+
+```ruby
+Peddler.configure do |config|
+  config.raise_on_server_errors = true
+end
+```
+
+This ensures consistent error handling and prevents silent failures from server errors.
+
+#### Current Default Behavior (v4.x)
+
+```ruby
+# Server errors (5xx) return response objects by default
+response = api.get_orders(marketplaceIds: ["ATVPDKIKX0DER"])
+
+# Must check status to detect server errors
+if response.status >= 500
+  puts "Server error: #{response.status}"
+  # Handle error or retry
+else
+  orders = response.parse["payload"]["orders"]
+end
+
+# Client errors (4xx) always raise
+begin
+  response = api.get_orders(marketplaceIds: ["INVALID"])
+rescue Peddler::Error => e
+  puts "Client error: #{e.message}"
+end
+```
+
+#### Recommended Behavior (v5.0)
+
+Enable consistent error handling by setting `raise_on_server_errors`:
+
+```ruby
+# Configure once at application startup
+Peddler.configure do |config|
+  config.raise_on_server_errors = true
+end
+
+# Now all errors raise exceptions consistently
+begin
+  response = api.get_orders(marketplaceIds: ["ATVPDKIKX0DER"])
+  orders = response.parse["payload"]["orders"]
+rescue Peddler::Error => e
+  puts "API Error: #{e.message}"
+  puts "Status: #{e.response.status}"
+  
+  # Handle retries for server errors
+  if e.response.status >= 500
+    # Retry logic here
+  end
+end
+```
+
+#### S3 Error Handling
+
+For file upload/download operations, Amazon S3 may return XML error responses. If Nokogiri is available, these are parsed for detailed error information:
+
+```ruby
+# With Nokogiri gem
+gem "nokogiri"
+
+# Enhanced S3 error parsing
+begin
+  api.upload_document(document_data)
+rescue Peddler::Error => e
+  puts "S3 Error: #{e.message}"  # Detailed XML-parsed error
+end
+```
+
+Without Nokogiri, S3 XML errors are still handled gracefully but with less detailed information.
+
 ### Available APIs
 
 Peddler provides Ruby interfaces to all Amazon SP-API endpoints. Each API is available in its respective version. Access APIs by calling methods on the Peddler module:
@@ -238,7 +327,15 @@ api.create_fulfillment_order(
 ```ruby
 api = Peddler.feeds(aws_region, access_token)
 
-# Create feed document
+# Complete Feeds API Workflow:
+# 1. Create a feed document (input feed document)
+# 2. Upload content to the document
+# 3. Create feed referencing the document
+# 4. Wait for feed to complete (e.g., SQS notification)
+# 5. Get feed document (result feed document)
+# 6. Download results to see processing outcome
+
+# Step 1: Create feed document (input document)
 document_response = api.create_feed_document(
   contentType: "text/xml; charset=UTF-8"
 )
@@ -262,11 +359,11 @@ upload_url = document_response.dig("url")
 # Access nested keys - returns nil if any key in the path is missing
 encryption_key = document_response.dig("encryptionDetails", "key")
 
-# Upload feed content
+# Step 2: Upload feed content to the input document
 feed_content = File.read("inventory_update.xml")
 api.upload_feed_document(upload_url, feed_content, "text/xml; charset=UTF-8")
 
-# Create feed
+# Step 3: Create feed referencing the input document
 feed_response = api.create_feed(
   feedType: "POST_INVENTORY_AVAILABILITY_DATA",
   marketplaceIds: ["ATVPDKIKX0DER"],
@@ -274,7 +371,32 @@ feed_response = api.create_feed(
 )
 feed_id = feed_response.dig("feedId")
 
-# Upload JSON feed
+# Step 4: Wait for feed to complete (polling or SQS notification)
+# Poll until status is "DONE", "FATAL", or "CANCELLED"
+loop do
+  feed_status = api.get_feed(feed_id)
+  status = feed_status.dig("processingStatus")
+  break if ["DONE", "FATAL", "CANCELLED"].include?(status)
+  sleep 30 # Wait 30 seconds before checking again
+end
+
+# Step 5: Get feed document (result document with processing results)
+result_document_id = feed_status.dig("resultFeedDocumentId")
+result_document = api.get_feed_document(result_document_id) if result_document_id
+
+# Step 6: Download results to see processing outcome
+if result_document
+  download_url = result_document.dig("url")
+  response = HTTP.get(download_url)
+  content = if result_document.dig("compressionAlgorithm") == "GZIP"
+              Zlib::GzipReader.new(response).read
+            else
+              response.to_s
+            end
+  # Parse content to check for errors/success
+end
+
+# JSON feed example
 json_document = api.create_feed_document(
   { "contentType" => "application/json; charset=UTF-8" }
 )
@@ -297,23 +419,39 @@ json_feed_content = JSON.generate({
   ]
 })
 api.upload_feed_document(json_document.dig("url"), json_feed_content, "application/json; charset=UTF-8")
-
-# Get feed status
-api.get_feed(feed_id)
-
-# Get feed document content
-document = api.get_feed_document(feed_document_id)
-download_url = document.dig("url")
-response = HTTP.get(download_url)
-content = Zlib::GzipReader.new(response).read if document.dig("compressionAlgorithm") == "GZIP"
 ```
 
 #### Communication and Customer Management APIs
 
+- **Customer Feedback API (2024-06-01)**: Analyze customer reviews and returns data at item and browse node levels
 - **Notifications API (v1)**: Subscribe to notifications for events like order updates
 - **Messaging API (v1)**: Send messages to customers
 - **Solicitations API (v1)**: Request customer reviews
 
+```ruby
+# Customer Feedback API example
+api = Peddler.customer_feedback_2024_06_01(aws_region, access_token)
+
+# Get item review topics (most positive and negative)
+review_topics = api.get_item_review_topics(
+  "B08N5WRWNW",  # ASIN
+  Marketplace.id("US"),
+  "frequency"  # Sort by frequency
+)
+
+# Get item review trends for past 6 months
+review_trends = api.get_item_review_trends(
+  "B08N5WRWNW",
+  Marketplace.id("US")
+)
+
+# Get browse node return topics
+return_topics = api.get_browse_node_return_topics(
+  "123456789",  # Browse node ID
+  Marketplace.id("US")
+)
+```
+
 ```ruby
 api = Peddler.notifications(aws_region, access_token)
 # Create destination
@@ -532,10 +670,9 @@ report = api.get_report(report_id)
 # Get all reports of a specific type
 reports = api.get_reports(report_types: ["GET_MERCHANTS_LISTINGS_FYP_REPORT"])
 
-# Download a report document
-document = api.get_report_document("DOCUMENT_ID")
-download_url = document.dig("url")
-# Process the downloaded report...
+# Download a report document (using convenience helper)
+response = api.download_report_document("DOCUMENT_ID")
+# Process the downloaded report content from response.body...
 ```
 
 #### Sellers API
@@ -549,11 +686,6 @@ participations = api.get_marketplace_participations
 
 For a complete list of available APIs and their detailed documentation, refer to the [API models repository](https://github.com/amzn/selling-partner-api-models).
 
-## TODO
-
-- [ ] Code generate payload parsers 🤔
-- [ ] Review and consider applying [these patches][patches]
-
 [build]: https://github.com/hakanensari/peddler/actions
 [docs-overview]: https://developer.amazonservices.com/sp-api-docs/overview
 [register-as-developer]: https://developer-docs.amazon.com/sp-api/docs/registering-as-a-developer
@@ -564,4 +696,3 @@ For a complete list of available APIs and their detailed documentation, refer to
 [authorization]: https://developer-docs.amazon.com/sp-api/docs/authorizing-selling-partner-api-applications
 [rate-limits]: https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits
 [httprb]: https://github.com/httprb/http
-[patches]: https://github.com/bizon/selling-partner-api-sdk/tree/master/codegen/patches

data/lib/peddler/api.rb

@@ -4,7 +4,6 @@ require "http"
 require "uri"
 
 require "peddler/endpoint"
-require "peddler/error"
 require "peddler/marketplace"
 require "peddler/response"
 require "peddler/version"
@@ -79,8 +78,6 @@ module Peddler
     def meter(requests_per_second)
       return self if retries.zero?
 
-      # HTTP v6.0 will implement retriable. Until then, point to their GitHub repo, or it's a no-op.
-      # https://github.com/httprb/http/pull/790
       delay = sandbox? ? 0.2 : 1.0 / requests_per_second
       retriable(delay:, tries: retries + 1, retry_statuses: [429])
 
@@ -107,7 +104,7 @@ module Peddler
     #   @return [self]
     [:via, :use, :retriable].each do |method|
       define_method(method) do |*args, **kwargs, &block|
-        @http = http.send(method, *args, **kwargs, &block) if http.respond_to?(method)
+        @http = http.send(method, *args, **kwargs, &block)
         self
       end
     end
@@ -124,13 +121,7 @@ module Peddler
         end
 
         response = http.send(method, uri, **options)
-
-        if response.status.client_error?
-          error = Error.build(response)
-          raise error if error
-        end
-
-        Response.decorate(response, parser:)
+        Response.wrap(response, parser:)
       end
     end
 

data/lib/peddler/apis/customer_feedback_2024_06_01.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "peddler/api"
+
+module Peddler
+  class << self
+    def customer_feedback_2024_06_01(...)
+      APIs::CustomerFeedback20240601.new(...)
+    end
+  end
+
+  module APIs
+    # The Selling Partner API for CustomerFeedback
+    #
+    # The Selling Partner API for Customer Feedback (Customer Feedback API) provides information about customer reviews
+    # and returns at both the item and browse node level.
+    class CustomerFeedback20240601 < API
+      # Retrieve an item's ten most positive and ten most negative review topics.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param asin [String] The Amazon Standard Identification Number (ASIN) is the unique identifier of a product
+      #   within a marketplace. The value must be a child ASIN.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @param sort_by [String] The metric by which to sort data in the response.
+      # @return [Peddler::Response] The API response
+      def get_item_review_topics(asin, marketplace_id, sort_by)
+        path = "/customerFeedback/2024-06-01/items/#{percent_encode(asin)}/reviews/topics"
+        params = {
+          "marketplaceId" => marketplace_id,
+          "sortBy" => sort_by,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # This API returns the associated browse node of the requested ASIN. A browse node is a location in a browse tree
+      # that is used for navigation, product classification, and website content on the Amazon retail website.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param asin [String] The Amazon Standard Identification Number (ASIN) is the unique identifier of a product
+      #   within a marketplace.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @return [Peddler::Response] The API response
+      def get_item_browse_node(asin, marketplace_id)
+        path = "/customerFeedback/2024-06-01/items/#{percent_encode(asin)}/browseNode"
+        params = {
+          "marketplaceId" => marketplace_id,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # Retrieve a browse node's ten most positive and ten most negative review topics.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param browse_node_id [String] The ID of a browse node. A browse node is a named location in a browse tree that
+      #   is used for navigation, product classification, and website content.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @param sort_by [String] The metric by which to sort the data in the response.
+      # @return [Peddler::Response] The API response
+      def get_browse_node_review_topics(browse_node_id, marketplace_id, sort_by)
+        path = "/customerFeedback/2024-06-01/browseNodes/#{percent_encode(browse_node_id)}/reviews/topics"
+        params = {
+          "marketplaceId" => marketplace_id,
+          "sortBy" => sort_by,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # Retrieve an item's positive and negative review trends for the past six months.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param asin [String] The Amazon Standard Identification Number (ASIN) is the unique identifier of a product
+      #   within a marketplace. This API takes child ASIN as an input.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @return [Peddler::Response] The API response
+      def get_item_review_trends(asin, marketplace_id)
+        path = "/customerFeedback/2024-06-01/items/#{percent_encode(asin)}/reviews/trends"
+        params = {
+          "marketplaceId" => marketplace_id,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # Retrieve the positive and negative review trends of items in a browse node for the past six months.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param browse_node_id [String] A browse node ID is a unique identifier of a browse node. A browse node is a
+      #   named location in a browse tree that is used for navigation, product classification, and website content.
+      # @param marketplace_id [String] The marketplace ID is the globally unique identifier of a marketplace. For more
+      #   information, refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids).
+      # @return [Peddler::Response] The API response
+      def get_browse_node_review_trends(browse_node_id, marketplace_id)
+        path = "/customerFeedback/2024-06-01/browseNodes/#{percent_encode(browse_node_id)}/reviews/trends"
+        params = {
+          "marketplaceId" => marketplace_id,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # Retrieve the topics that customers mention when they return items in a browse node.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param browse_node_id [String] A browse node ID is a unique identifier for a browse node. A browse node is a
+      #   named location in a browse tree that is used for navigation, product classification, and website content.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @return [Peddler::Response] The API response
+      def get_browse_node_return_topics(browse_node_id, marketplace_id)
+        path = "/customerFeedback/2024-06-01/browseNodes/#{percent_encode(browse_node_id)}/returns/topics"
+        params = {
+          "marketplaceId" => marketplace_id,
+        }.compact
+
+        get(path, params:)
+      end
+
+      # Retrieve the trends of topics that customers mention when they return items in a browse node.
+      #
+      # @note This operation can make a static sandbox call.
+      # @param browse_node_id [String] A browse node ID is a unique identifier of a browse node. A browse node is a
+      #   named location in a browse tree that is used for navigation, product classification, and website content.
+      # @param marketplace_id [String] The MarketplaceId is the globally unique identifier of a marketplace, you can
+      #   refer to the marketplaceId here : https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.
+      # @return [Peddler::Response] The API response
+      def get_browse_node_return_trends(browse_node_id, marketplace_id)
+        path = "/customerFeedback/2024-06-01/browseNodes/#{percent_encode(browse_node_id)}/returns/trends"
+        params = {
+          "marketplaceId" => marketplace_id,
+        }.compact
+
+        get(path, params:)
+      end
+    end
+  end
+end

data/lib/peddler/apis/finances_2024_06_19.rb

@@ -16,27 +16,35 @@ module Peddler
     # can obtain financial events for a given order or date range without having to wait until a statement period
     # closes.
     class Finances20240619 < API
-      # Returns transactions for the given parameters. It may take up to 48 hours for transactions to appear in your
-      # transaction events.
+      # Returns transactions for the given parameters. Financial events might not include orders from the last 48 hours.
       #
       # @note This operation can make a static sandbox call.
-      # @param posted_after [String] A date used for selecting transactions posted after (or at) a specified time. The
-      #   date-time must be no later than two minutes before the request was submitted, in ISO 8601 date time format.
+      # @param posted_after [String] The response includes financial events posted on or after this date. This date must
+      #   be in [ISO 8601](https://developer-docs.amazon.com/sp-api/docs/iso-8601) date-time format. The date-time must
+      #   be more than two minutes before the time of the request.
       # @param posted_before [String] A date used for selecting transactions posted before (but not at) a specified
       #   time. The date-time must be later than PostedAfter and no later than two minutes before the request was
       #   submitted, in ISO 8601 date time format. If PostedAfter and PostedBefore are more than 180 days apart, no
       #   transactions are returned. You must specify the PostedAfter parameter if you specify the PostedBefore
       #   parameter. Default: Now minus two minutes.
-      # @param marketplace_id [String] A string token used to select Marketplace ID.
+      # @param marketplace_id [String] The identifier of the marketplace from which you want to retrieve transactions.
+      #   The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace,
+      #   refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids).
+      # @param transaction_status [String] The status of the transaction. **Possible values:** * `DEFERRED`: the
+      #   transaction is currently deferred. * `RELEASED`: the transaction is currently released. * `DEFERRED_RELEASED`:
+      #   the transaction was deferred in the past, but is now released. The status of a deferred transaction is updated
+      #   to `DEFERRED_RELEASED` when the transaction is released.
       # @param next_token [String] A string token returned in the response of your previous request.
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
-      def list_transactions(posted_after, posted_before: nil, marketplace_id: nil, next_token: nil, rate_limit: 0.5)
+      def list_transactions(posted_after, posted_before: nil, marketplace_id: nil, transaction_status: nil,
+        next_token: nil, rate_limit: 0.5)
         path = "/finances/2024-06-19/transactions"
         params = {
           "postedAfter" => posted_after,
           "postedBefore" => posted_before,
           "marketplaceId" => marketplace_id,
+          "transactionStatus" => transaction_status,
           "nextToken" => next_token,
         }.compact
 

data/lib/peddler/apis/orders_v0.rb

@@ -162,7 +162,7 @@ module Peddler
       # Returns buyer information for the order that you specify.
       #
       # @note This operation can make a static sandbox call.
-      # @param order_id [String] An `orderId` is an Amazon-defined order identifier, in 3-7-7 format.
+      # @param order_id [String] The Amazon order identifier in 3-7-7 format.
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def get_order_buyer_info(order_id, rate_limit: 0.5)
@@ -174,7 +174,7 @@ module Peddler
       # Returns the shipping address for the order that you specify.
       #
       # @note This operation can make a static sandbox call.
-      # @param order_id [String] An `orderId` is an Amazon-defined order identifier, in 3-7-7 format.
+      # @param order_id [String] The Amazon order identifier in 3-7-7 format.
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def get_order_address(order_id, rate_limit: 0.5)
@@ -238,7 +238,7 @@ module Peddler
       # Returns regulated information for the order that you specify.
       #
       # @note This operation can make a static sandbox call.
-      # @param order_id [String] An Amazon-defined order identifier, in 3-7-7 format.
+      # @param order_id [String] The Amazon order identifier in 3-7-7 format.
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def get_order_regulated_info(order_id, rate_limit: 0.5)
@@ -250,7 +250,7 @@ module Peddler
       # Updates (approves or rejects) the verification status of an order containing regulated products.
       #
       # @note This operation can make a static sandbox call.
-      # @param order_id [String] An Amazon-defined order identifier, in 3-7-7 format.
+      # @param order_id [String] The Amazon order identifier in 3-7-7 format.
       # @param payload [Hash] The request body for the `updateVerificationStatus` operation.
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response

data/lib/peddler/apis/reports_2021_06_30.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "peddler/api"
+require "peddler/helpers/reports_2021_06_30"
 
 module Peddler
   class << self
@@ -15,6 +16,8 @@ module Peddler
     # The Selling Partner API for Reports lets you retrieve and manage a variety of reports that can help selling
     # partners manage their businesses.
     class Reports20210630 < API
+      include Peddler::Helpers::Reports20210630
+
       # Returns report details for the reports that match the filters that you specify.
       #
       # @note This operation can make a static sandbox call.

data/lib/peddler/apis/vendor_shipments_v1.rb

@@ -132,7 +132,7 @@ module Peddler
       #
       # @param limit [Integer] The limit to the number of records returned. Default value is 50 records.
       # @param sort_order [String] Sort the list by shipment label creation date in ascending or descending order.
-      # @param next_token [String] A token that is used to retrieve the next page of results. The response includes
+      # @param next_token [String] A token that you use to retrieve the next page of results. The response includes
       #   `nextToken` when the number of results exceeds the specified `pageSize` value. To get the next page of
       #   results, call the operation with this token and include the same arguments as the call that produced the
       #   token. To get a complete list, call this operation until `nextToken` is null. Note that this operation can

data/lib/peddler/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Peddler
+  class << self
+    attr_writer :raise_on_server_errors
+
+    def raise_on_server_errors
+      return @raise_on_server_errors if defined?(@raise_on_server_errors)
+
+      @raise_on_server_errors = false # Default to v4 behavior
+    end
+
+    def configure
+      yield self
+    end
+  end
+end

data/lib/peddler/error.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Peddler
   class Error < StandardError
     attr_reader :response
@@ -7,7 +9,11 @@ module Peddler
     # @!visibility private
     class << self
       def build(response)
-        payload = JSON.parse(response)
+        payload = begin
+          JSON.parse(response)
+        rescue JSON::ParserError
+          parse_xml_error(response)
+        end
 
         if payload.key?("error")
           class_name = normalize_class_name(payload["error"])
@@ -15,6 +21,9 @@ module Peddler
         elsif payload.key?("errors")
           class_name = normalize_class_name(payload.dig("errors", 0, "code"))
           message = payload.dig("errors", 0, "message")
+        elsif payload.key?("Code")
+          class_name = payload["Code"]
+          message = payload["Message"]
         else
           return
         end
@@ -22,10 +31,7 @@ module Peddler
         klass = if Errors.const_defined?(class_name)
           Errors.const_get(class_name)
         else
-          Errors.const_set(
-            class_name,
-            Class.new(Error),
-          )
+          Errors.const_set(class_name, Class.new(Error))
         end
 
         klass.new(message, response)
@@ -35,6 +41,14 @@ module Peddler
 
       private
 
+      def parse_xml_error(response)
+        require "nokogiri"
+        doc = Nokogiri::XML(response)
+        Hash[doc.root.elements.collect { |e| [e.name, e.text] }]
+      rescue LoadError, NoMethodError
+        {}
+      end
+
       def normalize_class_name(code)
         if code.match?(/\A([a-z_]+|[A-Z_]+)\z/)
           code.split("_").map(&:capitalize).join
@@ -51,6 +65,7 @@ module Peddler
   end
 
   module Errors
+    class AccessDenied < Error; end
     class InvalidGrant < Error; end
     class InvalidInput < Error; end
     class InvalidRequest < Error; end

data/lib/peddler/helpers/feeds_2021_06_30.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
+require "http"
+
+require "peddler/response"
+
 module Peddler
   module Helpers
     module Feeds20210630
-      # Uploads feed_content to a signed upload_url previously provided by
-      # create_feed_document. The upload_url is signed, the Host and content-type
-      # headers must match the signing.
+      # Convenience method to upload feed content to a signed upload_url previously
+      # provided by create_feed_document. This is step 2 of the 6-step Feeds API workflow.
+      # See README.md for the complete workflow documentation.
+      #
+      # The upload_url is signed, the Host and content-type headers must match the signing.
       # @param upload_url [String] The signed url from the `create_feed_document` response.
       # @param feed_content [String] The body of the content to upload.
       # @param content_type [String] The content type of the upload,
@@ -14,12 +20,20 @@ module Peddler
       def upload_feed_document(upload_url, feed_content, content_type)
         response = HTTP.headers("content-type" => content_type).put(upload_url, body: feed_content)
 
-        if response.status.client_error?
-          error = Error.build(response)
-          raise error if error
-        end
+        Response.wrap(response, parser:)
+      end
+
+      # Convenience method to download result feed content from a signed download_url
+      # provided by get_feed_document. This is step 6 of the 6-step Feeds API workflow.
+      # See README.md for the complete workflow documentation.
+      #
+      # The download_url is signed and provides access to the processed feed results.
+      # @param download_url [String] The signed url from the `get_feed_document` response.
+      # @return [HTTP::Response] The API response containing the feed result document
+      def download_result_feed_document(download_url)
+        response = HTTP.get(download_url)
 
-        response
+        Response.wrap(response, parser:)
       end
     end
   end

data/lib/peddler/helpers/reports_2021_06_30.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "http"
+
+require "peddler/response"
+require "peddler/error"
+
+module Peddler
+  module Helpers
+    module Reports20210630
+      # Convenience method to download a report by its document ID or URL.
+      # This method can handle both document IDs and direct download URLs.
+      #
+      # @param report_document_id_or_url [String] The report document identifier or download URL
+      # @return [HTTP::Response] The API response containing the report content
+      def download_report_document(report_document_id_or_url)
+        # If it looks like a URL, use direct download
+        if report_document_id_or_url.start_with?("http")
+          return download_report_document_from_url(report_document_id_or_url)
+        end
+
+        # Otherwise, treat it as a document ID and get the download URL first
+        document_info = get_report_document(report_document_id_or_url)
+        download_url = document_info.dig("url")
+
+        download_report_document_from_url(download_url)
+      end
+
+      private
+
+      def download_report_document_from_url(download_url)
+        response = HTTP.get(download_url)
+
+        Response.wrap(response, parser:)
+      end
+    end
+  end
+end

data/lib/peddler/marketplace.rb

@@ -77,6 +77,20 @@ module Peddler
           new(**values, country_code: country_code)
         end
       end
+
+      # Dynamically generate shorthand methods for each country code
+      # e.g., Marketplace.us returns the US marketplace
+      MARKETPLACE_IDS.each_key do |country_code|
+        method_name = country_code.downcase
+        define_method(method_name) do
+          find(country_code)
+        end
+      end
+
+      # Special alias for GB (Great Britain) -> UK
+      define_method(:gb) do
+        find("GB")
+      end
     end
 
     # @return [Peddler::Endpoint]

data/lib/peddler/response.rb

@@ -3,6 +3,9 @@
 require "delegate"
 require "forwardable"
 
+require "peddler/config"
+require "peddler/error"
+
 module Peddler
   # Wraps HTTP::Response to allow custom parsing
   class Response < SimpleDelegator
@@ -17,16 +20,60 @@ module Peddler
     def_delegator :to_h, :dig
 
     class << self
-      # Decorates an HTTP::Response
+      # Wraps an HTTP::Response with parsing capabilities
       #
       # @param [HTTP::Response] response
       # @param [nil, #call] parser (if any)
-      # @return [ResponseDecorator]
-      def decorate(response, parser: nil)
-        new(response).tap do |decorator|
-          decorator.parser = parser
+      # @return [Response]
+      # @raise [Error] if response status indicates an error (>= 400)
+      def wrap(response, parser: nil)
+        # Check for HTTP errors and raise custom Peddler errors
+        if response.status >= 400
+          # Client errors (4xx) always raise
+          if response.status < 500
+            error = Error.build(response)
+            raise error || Error.new(response.status, response)
+          # Server errors (5xx) - check configuration
+          elsif Peddler.raise_on_server_errors
+            error = Error.build(response)
+            raise error || Error.new(response.status, response)
+          else
+            # Emit deprecation warning for v4 behavior
+            warn_about_server_error_handling
+          end
+        end
+
+        new(response).tap do |wrapper|
+          wrapper.parser = parser
         end
       end
+
+      # @deprecated Use {.wrap} instead
+      def decorate(...)
+        warn("Response.decorate is deprecated and will be removed in v5.0. Use Response.wrap instead.", uplevel: 1)
+        wrap(...)
+      end
+
+      private
+
+      def warn_about_server_error_handling
+        return if @deprecation_warned
+
+        @deprecation_warned = true
+
+        warn(<<~MSG)
+          [DEPRECATION] Peddler v4 behavior: Server errors (5xx) are returning response objects instead of raising exceptions.
+          This behavior is deprecated and will change in Peddler v5.0.
+
+          To adopt the new behavior now and silence this warning:
+
+            Peddler.configure do |config|
+              config.raise_on_server_errors = true
+            end
+
+          For more information, see: https://github.com/hakanensari/peddler/blob/main/CHANGELOG.md
+        MSG
+      end
     end
 
     # @return [#call]

data/lib/peddler/token.rb

@@ -2,7 +2,7 @@
 
 require "http"
 
-require "peddler/error"
+require "peddler/response"
 
 module Peddler
   # Requests refresh and access tokens that authorize your application to take actions on behalf of a selling partner.
@@ -31,13 +31,7 @@ module Peddler
 
     def request
       response = HTTP.post(URL, form: params)
-
-      if response.status.client_error?
-        error = Error.build(response)
-        raise error if error
-      end
-
-      response
+      Response.wrap(response)
     end
 
     def grant_type

data/lib/peddler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Peddler
-  VERSION = "4.4.0"
+  VERSION = "4.5.0"
 end

data/lib/peddler.rb

@@ -7,6 +7,7 @@ require "peddler/apis/application_management_2023_11_30"
 require "peddler/apis/catalog_items_2020_12_01"
 require "peddler/apis/catalog_items_2022_04_01"
 require "peddler/apis/catalog_items_v0"
+require "peddler/apis/customer_feedback_2024_06_01"
 require "peddler/apis/data_kiosk_2023_11_15"
 require "peddler/apis/easy_ship_2022_03_23"
 require "peddler/apis/fba_inbound_eligibility_v1"
@@ -57,6 +58,7 @@ require "peddler/apis/vendor_invoices_v1"
 require "peddler/apis/vendor_orders_v1"
 require "peddler/apis/vendor_shipments_v1"
 require "peddler/apis/vendor_transaction_status_v1"
+require "peddler/config"
 require "peddler/token"
 
 module Peddler
@@ -66,6 +68,7 @@ module Peddler
     alias_method :application_integrations, :application_integrations_2024_04_01
     alias_method :application_management, :application_management_2023_11_30
     alias_method :catalog_items, :catalog_items_2022_04_01
+    alias_method :customer_feedback, :customer_feedback_2024_06_01
     alias_method :data_kiosk, :data_kiosk_2023_11_15
     alias_method :easy_ship, :easy_ship_2022_03_23
     alias_method :fba_inbound_eligibility, :fba_inbound_eligibility_v1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: peddler
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Hakan Ensari
@@ -13,22 +13,16 @@ dependencies:
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '5.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '5.3'
 email:
 - hakanensari@gmail.com
 executables: []
@@ -46,6 +40,7 @@ files:
 - lib/peddler/apis/catalog_items_2020_12_01.rb
 - lib/peddler/apis/catalog_items_2022_04_01.rb
 - lib/peddler/apis/catalog_items_v0.rb
+- lib/peddler/apis/customer_feedback_2024_06_01.rb
 - lib/peddler/apis/data_kiosk_2023_11_15.rb
 - lib/peddler/apis/easy_ship_2022_03_23.rb
 - lib/peddler/apis/fba_inbound_eligibility_v1.rb
@@ -96,9 +91,11 @@ files:
 - lib/peddler/apis/vendor_orders_v1.rb
 - lib/peddler/apis/vendor_shipments_v1.rb
 - lib/peddler/apis/vendor_transaction_status_v1.rb
+- lib/peddler/config.rb
 - lib/peddler/endpoint.rb
 - lib/peddler/error.rb
 - lib/peddler/helpers/feeds_2021_06_30.rb
+- lib/peddler/helpers/reports_2021_06_30.rb
 - lib/peddler/marketplace.rb
 - lib/peddler/response.rb
 - lib/peddler/token.rb