peddler 4.4.0 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 747dd42d445c711adc43f20e6a9c479bf795352512fecc67814f1a5f698c86a9
-  data.tar.gz: 134255293900b9c32086f2291a42498e1477f29df64cbe0aa8b3da1420dfe320
+  metadata.gz: ba82042badf4244382b3940ce49aee56c54f8558da34e2036c1b86bc39a92d80
+  data.tar.gz: e287aa77f2ec37862c8f14480389b8a0a650141932fd0fbc301411cc8695402c
 SHA512:
-  metadata.gz: 5880a513c77e79ae8523ca96c69d65697c179ede0febc18f2b4a10d932e7de9ed32cdf74c82ff13bc68ca7c15ae6df9d84ec92150d7bc018da6778e104dcb889
-  data.tar.gz: 60b00292980fdac6da6acccac237b0ce677f7e49cb001f72584426aa70d54deac3c84d9e89abc5e380cf94aecda6db0d695d39868644380acb8c86603245e30d
+  metadata.gz: 7dc987e9271cd6f711669c9faaa30075afcc5c07b08137ab7f5e2a3422b74da67b698e9e477850a099906324178abc95c693f4460b286c58fe643a971986c80f
+  data.tar.gz: 23ce12ffd930ed067aa3d1e67d4b2439b4b52cd9f90f2b1cce00d214d2f323259091d57ac7ad22e10b55f6a3fb825e04ba019739673ff77ea5c1d21c36a4c8f1

data/README.md

@@ -1,10 +1,10 @@
 # Peddler
 
-[![Build](https://github.com/hakanensari/peddler/workflows/build/badge.svg)][build]
+[![Build](https://github.com/lineofflight/peddler/actions/workflows/ci.yml/badge.svg)][build]
 
 **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,124 @@ api.get_orders(
 )
 ```
 
+### Typed Responses
+
+Peddler provides typed response parsing using the [Structure gem](https://github.com/hakanensari/structure), offering runtime type checking and better IDE support:
+
+```ruby
+# Enable typed responses
+api = Peddler.orders(aws_region, access_token).typed
+
+# Get orders with type-safe response
+response = api.get_orders(
+  marketplaceIds: ["ATVPDKIKX0DER"],
+  createdAfter: "2023-01-01T00:00:00Z"
+)
+
+# Access data with type safety
+orders = response.payload.orders  # Returns array of Order objects
+order = orders.first
+
+# Type-safe attribute access
+order.amazon_order_id     # => "123-4567890-1234567"
+order.order_status        # => "Shipped"
+order.is_prime            # => true
+order.order_total         # => Money object (automatic coercion)
+order.order_total.cents   # => 9999
+order.order_total.currency.iso_code # => "USD"
+```
+
+#### Hash Access
+
+If you prefer working with plain hashes, use the standard (non-typed) API:
+
+```ruby
+api = Peddler.orders(aws_region, access_token)
+response = api.get_orders(marketplaceIds: ["ATVPDKIKX0DER"])
+orders = response.dig("payload", "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 +364,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 +396,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 +408,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 +456,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 +707,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 +723,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 +733,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

@@ -3,6 +3,7 @@
 require "http"
 require "uri"
 
+require "peddler/config"
 require "peddler/endpoint"
 require "peddler/error"
 require "peddler/marketplace"
@@ -15,11 +16,6 @@ module Peddler
     class CannotSandbox < StandardError; end
     class MustSandbox < StandardError; end
 
-    class << self
-      # @return [#call]
-      attr_accessor :parser
-    end
-
     # @return [Peddler::Endpoint]
     attr_reader :endpoint
 
@@ -46,6 +42,20 @@ module Peddler
       sandbox? ? endpoint.sandbox : endpoint.production
     end
 
+    # Enables typed response parsing
+    # @return [self]
+    def typed
+      load_types
+      @typed = true
+
+      self
+    end
+
+    # @return [Boolean]
+    def typed?
+      !!@typed
+    end
+
     # Switches to the SP-API sandbox to make test calls
     #
     # @see https://developer-docs.amazon.com/sp-api/docs/the-selling-partner-api-sandbox
@@ -79,8 +89,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,14 +115,14 @@ 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
     alias_method :through, :via
 
     [:get, :post, :put, :delete, :patch].each do |method|
-      define_method(method) do |path, **options|
+      define_method(method) do |path, parser: nil, **options|
         if options[:body] && !options[:body].is_a?(String)
           options[:json] = options.delete(:body)
         end
@@ -123,25 +131,12 @@ module Peddler
           uri.path = path
         end
 
-        response = http.send(method, uri, **options)
-
-        if response.status.client_error?
-          error = Error.build(response)
-          raise error if error
-        end
+        http_response = http.send(method, uri, **options)
 
-        Response.decorate(response, parser:)
+        Response.wrap(http_response, parser:)
       end
     end
 
-    attr_writer :parser
-
-    # @!attribute parser
-    # @return [#call]
-    def parser
-      @parser || self.class.parser
-    end
-
     private
 
     def cannot_sandbox!
@@ -160,6 +155,10 @@ module Peddler
       Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
     end
 
+    def load_types
+      raise NotImplementedError, "subclasses must implement #load_types"
+    end
+
     # Encodes URL path components
     def percent_encode(component)
       URI.encode_uri_component(component)

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09.rb

@@ -14,6 +14,8 @@ module Peddler
     #
     # The Selling Partner API for Amazon Warehousing and Distribution (AWD) provides programmatic access to information
     # about AWD shipments and inventory.
+    #
+    # @see https://github.com/amzn/selling-partner-api-models/blob/main/models/awd_2024-05-09.json
     class AmazonWarehousingAndDistribution20240509 < API
       # Creates a draft AWD inbound order with a list of packages for inbound shipment. The operation creates one
       # shipment per order.
@@ -24,8 +26,8 @@ module Peddler
       # @return [Peddler::Response] The API response
       def create_inbound(body, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundOrders"
-
-        meter(rate_limit).post(path, body:)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::InboundOrderReference if typed?
+        meter(rate_limit).post(path, body:, parser:)
       end
 
       # Retrieves an AWD inbound order.
@@ -36,8 +38,8 @@ module Peddler
       # @return [Peddler::Response] The API response
       def get_inbound(order_id, rate_limit: 2.0)
         path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}"
-
-        meter(rate_limit).get(path)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::InboundOrder if typed?
+        meter(rate_limit).get(path, parser:)
       end
 
       # Updates an AWD inbound order that is in `DRAFT` status and not yet confirmed. Use this operation to update the
@@ -50,7 +52,6 @@ module Peddler
       # @return [Peddler::Response] The API response
       def update_inbound(order_id, body, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}"
-
         meter(rate_limit).put(path, body:)
       end
 
@@ -62,7 +63,6 @@ module Peddler
       # @return [Peddler::Response] The API response
       def cancel_inbound(order_id, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}/cancellation"
-
         meter(rate_limit).post(path)
       end
 
@@ -74,7 +74,6 @@ module Peddler
       # @return [Peddler::Response] The API response
       def confirm_inbound(order_id, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}/confirmation"
-
         meter(rate_limit).post(path)
       end
 
@@ -91,8 +90,8 @@ module Peddler
         params = {
           "skuQuantities" => sku_quantities,
         }.compact
-
-        meter(rate_limit).get(path, params:)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::InboundShipment if typed?
+        meter(rate_limit).get(path, params:, parser:)
       end
 
       # Retrieves the box labels for a shipment ID that you specify. This is an asynchronous operation. If the label
@@ -111,8 +110,8 @@ module Peddler
           "pageType" => page_type,
           "formatType" => format_type,
         }.compact
-
-        meter(rate_limit).get(path, params:)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::ShipmentLabels if typed?
+        meter(rate_limit).get(path, params:, parser:)
       end
 
       # Updates transport details for an AWD shipment.
@@ -124,7 +123,6 @@ module Peddler
       # @return [Peddler::Response] The API response
       def update_inbound_shipment_transport_details(shipment_id, body, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundShipments/#{percent_encode(shipment_id)}/transport"
-
         meter(rate_limit).put(path, body:)
       end
 
@@ -137,8 +135,8 @@ module Peddler
       # @return [Peddler::Response] The API response
       def check_inbound_eligibility(body, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundEligibility"
-
-        meter(rate_limit).post(path, body:)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::InboundEligibility if typed?
+        meter(rate_limit).post(path, body:, parser:)
       end
 
       # Retrieves a summary of all the inbound AWD shipments associated with a merchant, with the ability to apply
@@ -173,8 +171,8 @@ module Peddler
           "maxResults" => max_results,
           "nextToken" => next_token,
         }.compact
-
-        meter(rate_limit).get(path, params:)
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::ShipmentListing if typed?
+        meter(rate_limit).get(path, params:, parser:)
       end
 
       # Lists AWD inventory associated with a merchant with the ability to apply optional filters.
@@ -201,8 +199,14 @@ module Peddler
           "nextToken" => next_token,
           "maxResults" => max_results,
         }.compact
+        parser = Peddler::Types::AmazonWarehousingAndDistribution20240509::InventoryListing if typed?
+        meter(rate_limit).get(path, params:, parser:)
+      end
+
+      private
 
-        meter(rate_limit).get(path, params:)
+      def load_types
+        require "peddler/types/amazon_warehousing_and_distribution_2024_05_09"
       end
     end
   end