Fix documentation [#172]

Also, renamed `ResponseDecorator` to `Response` to make the interface
more intuitive and keep the decorator pattern an internal detail.

lib/generator/operation.rb

@@ -58,7 +58,7 @@ def tags
       elsif dynamic_sandbox?
         output.unshift("@note This operation can make a dynamic sandbox call.")
       end
-      output << "@return [Hash] The API response"
+      output << "@return [Peddler::Response] The API response"
 
       output.map do |line|
         line = convert_html_links_to_yard(line)

lib/peddler/api.rb

@@ -5,7 +5,7 @@
 require "peddler/endpoint"
 require "peddler/error"
 require "peddler/marketplace"
-require "peddler/response_decorator"
+require "peddler/response"
 require "peddler/version"
 
 module Peddler
@@ -120,7 +120,7 @@ def meter(rate_limit)
           raise error if error
         end
 
-        ResponseDecorator.decorate(response, parser:)
+        Response.decorate(response, parser:)
       end
     end
 

lib/peddler/api/amazon_warehousing_and_distribution_2024_05_09.rb

@@ -22,7 +22,7 @@ class AmazonWarehousingAndDistribution20240509 < API
       # @param sku_quantities [String] If equal to `SHOW`, the response includes the shipment SKU quantity details.
       #   Defaults to `HIDE`, in which case the response does not contain SKU quantities
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
         path = "/awd/2024-05-09/inboundShipments/#{shipment_id}"
         params = {
@@ -47,7 +47,7 @@ def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
       # @param max_results [Integer] Maximum number of results to return.
       # @param next_token [String] Token to retrieve the next set of paginated results.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_inbound_shipments(sort_by: nil, sort_order: nil, shipment_status: nil, updated_after: nil,
         updated_before: nil, max_results: 25, next_token: nil, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundShipments"
@@ -74,7 +74,7 @@ def list_inbound_shipments(sort_by: nil, sort_order: nil, shipment_status: nil,
       # @param next_token [String] Token to retrieve the next set of paginated results.
       # @param max_results [Integer] Maximum number of results to return.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_inventory(sku: nil, sort_order: nil, details: nil, next_token: nil, max_results: 25, rate_limit: 2.0)
         path = "/awd/2024-05-09/inventory"
         params = {

lib/peddler/api/aplus_content_2020_11_01.rb

@@ -28,7 +28,7 @@ class AplusContent20201101 < API
       #   other parameter will cause the request to fail. When no nextPageToken value is returned there are no more
       #   pages to return. A pageToken value is not usable across different operations.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def search_content_documents(marketplace_id, page_token: nil, rate_limit: 10.0)
         cannot_sandbox!
 
@@ -46,7 +46,7 @@ def search_content_documents(marketplace_id, page_token: nil, rate_limit: 10.0)
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param post_content_document_request [Hash] The content document request details.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def create_content_document(marketplace_id, post_content_document_request, rate_limit: 10.0)
         cannot_sandbox!
 
@@ -67,7 +67,7 @@ def create_content_document(marketplace_id, post_content_document_request, rate_
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param included_data_set [Array<String>] The set of A+ Content data types to include in the response.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_content_document(content_reference_key, marketplace_id, included_data_set, rate_limit: 10.0)
         cannot_sandbox!
 
@@ -88,7 +88,7 @@ def get_content_document(content_reference_key, marketplace_id, included_data_se
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param post_content_document_request [Hash] The content document request details.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def update_content_document(content_reference_key, marketplace_id, post_content_document_request,
         rate_limit: 10.0)
         cannot_sandbox!
@@ -118,7 +118,7 @@ def update_content_document(content_reference_key, marketplace_id, post_content_
       #   other parameter will cause the request to fail. When no nextPageToken value is returned there are no more
       #   pages to return. A pageToken value is not usable across different operations.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_content_document_asin_relations(content_reference_key, marketplace_id, included_data_set: nil,
         asin_set: nil, page_token: nil, rate_limit: 10.0)
         cannot_sandbox!
@@ -144,7 +144,7 @@ def list_content_document_asin_relations(content_reference_key, marketplace_id,
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param post_content_document_asin_relations_request [Hash] The content document ASIN relations request details.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def post_content_document_asin_relations(content_reference_key, marketplace_id,
         post_content_document_asin_relations_request, rate_limit: 10.0)
         cannot_sandbox!
@@ -164,7 +164,7 @@ def post_content_document_asin_relations(content_reference_key, marketplace_id,
       # @param asin_set [Array<String>] The set of ASINs.
       # @param post_content_document_request [Hash] The content document request details.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def validate_content_document_asin_relations(marketplace_id, post_content_document_request, asin_set: nil,
         rate_limit: 10.0)
         cannot_sandbox!
@@ -189,7 +189,7 @@ def validate_content_document_asin_relations(marketplace_id, post_content_docume
       #   other parameter will cause the request to fail. When no nextPageToken value is returned there are no more
       #   pages to return. A pageToken value is not usable across different operations.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def search_content_publish_records(marketplace_id, asin, page_token: nil, rate_limit: 10.0)
         cannot_sandbox!
 
@@ -210,7 +210,7 @@ def search_content_publish_records(marketplace_id, asin, page_token: nil, rate_l
       #   any A+ content identifier.
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def post_content_document_approval_submission(content_reference_key, marketplace_id, rate_limit: 10.0)
         cannot_sandbox!
 
@@ -230,7 +230,7 @@ def post_content_document_approval_submission(content_reference_key, marketplace
       #   any A+ content identifier.
       # @param marketplace_id [String] The identifier for the marketplace where the A+ Content is published.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def post_content_document_suspend_submission(content_reference_key, marketplace_id, rate_limit: 10.0)
         cannot_sandbox!
 

lib/peddler/api/application_integrations_2024_04_01.rb

@@ -20,7 +20,7 @@ class ApplicationIntegrations20240401 < API
       # @note This operation can make a static sandbox call.
       # @param body [Hash] The request body for the `createNotification` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def create_notification(body, rate_limit: 1.0)
         path = "/appIntegrations/2024-04-01/notifications"
 
@@ -32,7 +32,7 @@ def create_notification(body, rate_limit: 1.0)
       # @note This operation can make a static sandbox call.
       # @param body [Hash] The request body for the `deleteNotifications` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def delete_notifications(body, rate_limit: 1.0)
         path = "/appIntegrations/2024-04-01/notifications/deletion"
 
@@ -45,7 +45,7 @@ def delete_notifications(body, rate_limit: 1.0)
       # @param notification_id [String] A `notificationId` uniquely identifies a notification.
       # @param body [Hash] The request body for the `recordActionFeedback` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def record_action_feedback(notification_id, body, rate_limit: 1.0)
         path = "/appIntegrations/2024-04-01/notifications/#{notification_id}/feedback"
 

lib/peddler/api/application_management_2023_11_30.rb

@@ -22,7 +22,7 @@ class ApplicationManagement20231130 < API
       # secret](https://developer-docs.amazon.com/sp-api/v0/docs/application-management-api-v2023-11-30-use-case-guide#tutorial-rotate-your-applications-client-secret).
       #
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def rotate_application_client_secret(rate_limit: 0.0167)
         cannot_sandbox!
 

lib/peddler/api/catalog_items_2020_12_01.rb

@@ -35,7 +35,7 @@ class CatalogItems20201201 < API
       # @param locale [String] Locale for retrieving localized summaries. Defaults to the primary locale of the
       #   marketplace.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def search_catalog_items(keywords, marketplace_ids, included_data: "summaries", brand_names: nil,
         classification_ids: nil, page_size: 10, page_token: nil, keywords_locale: nil, locale: nil, rate_limit: 2.0)
         path = "/catalog/2020-12-01/items"
@@ -65,7 +65,7 @@ def search_catalog_items(keywords, marketplace_ids, included_data: "summaries",
       # @param locale [String] Locale for retrieving localized summaries. Defaults to the primary locale of the
       #   marketplace.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_catalog_item(asin, marketplace_ids, included_data: "summaries", locale: nil, rate_limit: 2.0)
         path = "/catalog/2020-12-01/items/#{asin}"
         params = {

lib/peddler/api/catalog_items_2022_04_01.rb

@@ -43,7 +43,7 @@ class CatalogItems20220401 < API
       # @param keywords_locale [String] The language of the keywords provided for `keywords`-based queries. Defaults to
       #   the primary locale of the marketplace. **Note:** Cannot be used with `identifiers`.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def search_catalog_items(marketplace_ids, identifiers: nil, identifiers_type: nil, included_data: ["summaries"],
         locale: nil, seller_id: nil, keywords: nil, brand_names: nil, classification_ids: nil, page_size: 10,
         page_token: nil, keywords_locale: nil, rate_limit: 2.0)
@@ -77,7 +77,7 @@ def search_catalog_items(marketplace_ids, identifiers: nil, identifiers_type: ni
       # @param locale [String] Locale for retrieving localized summaries. Defaults to the primary locale of the
       #   marketplace.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_catalog_item(asin, marketplace_ids, included_data: ["summaries"], locale: nil, rate_limit: 2.0)
         path = "/catalog/2022-04-01/items/#{asin}"
         params = {

lib/peddler/api/catalog_items_v0.rb

@@ -40,7 +40,7 @@ class CatalogItemsV0 < API
       # @param jan [String] A Japanese article number that uniquely identifies the product, manufacturer, and its
       #   attributes.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_catalog_items(marketplace_id, query: nil, query_context_id: nil, seller_sku: nil, upc: nil, ean: nil,
         isbn: nil, jan: nil, rate_limit: nil)
         path = "/catalog/v0/items"
@@ -69,7 +69,7 @@ def list_catalog_items(marketplace_id, query: nil, query_context_id: nil, seller
       # @param marketplace_id [String] A marketplace identifier. Specifies the marketplace for the item.
       # @param asin [String] The Amazon Standard Identification Number (ASIN) of the item.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_catalog_item(marketplace_id, asin, rate_limit: nil)
         path = "/catalog/v0/items/#{asin}"
         params = {
@@ -87,7 +87,7 @@ def get_catalog_item(marketplace_id, asin, rate_limit: nil)
       # @param seller_sku [String] Used to identify items in the given marketplace. SellerSKU is qualified by the
       #   seller's SellerId, which is included with every operation that you submit.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_catalog_categories(marketplace_id, asin: nil, seller_sku: nil, rate_limit: 1.0)
         path = "/catalog/v0/categories"
         params = {

lib/peddler/api/data_kiosk_2023_11_15.rb

@@ -31,7 +31,7 @@ class DataKiosk20231115 < API
       #   with the request that generated this token, with the exception of `pageSize` which can be modified between
       #   calls to `getQueries`. In the absence of this token value, `getQueries` returns the first page of results.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_queries(processing_statuses: nil, page_size: 10, created_since: nil, created_until: nil,
         pagination_token: nil, rate_limit: 0.0222)
         path = "/dataKiosk/2023-11-15/queries"
@@ -55,7 +55,7 @@ def get_queries(processing_statuses: nil, page_size: 10, created_since: nil, cre
       # @note This operation can make a static sandbox call.
       # @param body [Hash] The body of the request.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def create_query(body, rate_limit: 0.0167)
         path = "/dataKiosk/2023-11-15/queries"
 
@@ -71,7 +71,7 @@ def create_query(body, rate_limit: 0.0167)
       # @param query_id [String] The identifier for the query. This identifier is unique only in combination with a
       #   selling partner account ID.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def cancel_query(query_id, rate_limit: 0.0222)
         path = "/dataKiosk/2023-11-15/queries/#{query_id}"
 
@@ -84,7 +84,7 @@ def cancel_query(query_id, rate_limit: 0.0222)
       # @note This operation can make a static sandbox call.
       # @param query_id [String] The query identifier.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_query(query_id, rate_limit: 2.0)
         path = "/dataKiosk/2023-11-15/queries/#{query_id}"
 
@@ -97,7 +97,7 @@ def get_query(query_id, rate_limit: 2.0)
       # @note This operation can make a static sandbox call.
       # @param document_id [String] The identifier for the Data Kiosk document.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_document(document_id, rate_limit: 0.0167)
         path = "/dataKiosk/2023-11-15/documents/#{document_id}"
 

lib/peddler/api/easy_ship_2022_03_23.rb

@@ -30,7 +30,7 @@ class EasyShip20220323 < API
       # @note This operation can make a static sandbox call.
       # @param list_handover_slots_request [Hash] The request schema for the `listHandoverSlots` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def list_handover_slots(list_handover_slots_request: nil, rate_limit: 1.0)
         path = "/easyShip/2022-03-23/timeSlot"
         body = list_handover_slots_request
@@ -46,7 +46,7 @@ def list_handover_slots(list_handover_slots_request: nil, rate_limit: 1.0)
       #   to deliver using Amazon Easy Ship.
       # @param marketplace_id [String] An identifier for the marketplace in which the seller is selling.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def get_scheduled_package(amazon_order_id, marketplace_id, rate_limit: 1.0)
         path = "/easyShip/2022-03-23/package"
         params = {
@@ -71,7 +71,7 @@ def get_scheduled_package(amazon_order_id, marketplace_id, rate_limit: 1.0)
       # @note This operation can make a static sandbox call.
       # @param create_scheduled_package_request [Hash] The request schema for the `createScheduledPackage` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def create_scheduled_package(create_scheduled_package_request, rate_limit: 1.0)
         path = "/easyShip/2022-03-23/package"
         body = create_scheduled_package_request
@@ -88,7 +88,7 @@ def create_scheduled_package(create_scheduled_package_request, rate_limit: 1.0)
       # @note This operation can make a static sandbox call.
       # @param update_scheduled_packages_request [Hash] The request schema for the `updateScheduledPackages` operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def update_scheduled_packages(update_scheduled_packages_request: nil, rate_limit: 1.0)
         path = "/easyShip/2022-03-23/package"
         body = update_scheduled_packages_request
@@ -115,7 +115,7 @@ def update_scheduled_packages(update_scheduled_packages_request: nil, rate_limit
       # @param create_scheduled_packages_request [Hash] The request schema for the `createScheduledPackageBulk`
       #   operation.
       # @param rate_limit [Float] Requests per second
-      # @return [Hash] The API response
+      # @return [Peddler::Response] The API response
       def create_scheduled_package_bulk(create_scheduled_packages_request, rate_limit: 1.0)
         path = "/easyShip/2022-03-23/packages/bulk"
         body = create_scheduled_packages_request