peddler 5.0.0.pre.2 → 5.0.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20b378be071f3a0cade83e11f4c9970aa5d00ad4077097fd4ac22d709b20bf3d
-  data.tar.gz: 86420f4e6823a302e9785c2f795714f3769dce647e7880dcdee0bf5cdfd6b94b
+  metadata.gz: dce693a55301af876ea952055d0d4b04ba5470f0f85f88b7171acb14f185d0ff
+  data.tar.gz: 7d7d76d1eb94e784002021fc6ffc9d5135d2638c1c4ffdbccfced840272af334
 SHA512:
-  metadata.gz: 6cd309742cd1cc9594c570171553137ab43966cb3060f1af36a6da17a8c15f56cb4f93cd60f06bb06425a05e2d97108209f4e164890c5d574fabe0ac237e62c5
-  data.tar.gz: c5762d1e6b36d83dd7cbc0348d3ae6500bc983015e5efdd6c772d56d853aa8155f92a485e8292f2d4acc2501c333437685dd41fde8871d13f247b6db812ae518
+  metadata.gz: bab7c5e1c449c7cc69ebea6f3047356ef98adf68367aa8d7d5a4fd913367df2387fc705f284bbf20e20c50d73b49260c500599e01815a13fb9aaa7a98f2d3faf
+  data.tar.gz: 875b3b3dcd09055844437b25513df1b8a0d13842238ddda7c2d428fca620b21fdca968b6beb7b342a8e30e8bcd294a63ecff561b58d80a9236015ad849c427b1

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build](https://github.com/lineofflight/peddler/actions/workflows/ci.yml/badge.svg)][build]
 
-> **IMPORTANT:** This README is for the v5.0.0.pre.1 pre-release. For the latest stable version, see the [v4.9.0 README](https://github.com/hakanensari/peddler/blob/v4.9.0/README.md).
+> **IMPORTANT:** This README is for the v5 pre-release. For the latest stable version, see the [v4.9.0 README](https://github.com/hakanensari/peddler/blob/v4.9.0/README.md).
 
 **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.
 
@@ -20,7 +20,7 @@ To begin using the Amazon SP-API, you must [register as a developer][register-as
 Add this line to your Gemfile.
 
 ```ruby
-gem "peddler", "~> 5.0.0.pre.1"
+gem "peddler", "~> 5.0.0.pre.2"
 ```
 
 And then execute:
@@ -399,6 +399,41 @@ json_feed_content = JSON.generate({
 api.upload_feed_document(json_document.dig("url"), json_feed_content, "application/json; charset=UTF-8")
 ```
 
+**Parsing Feed Results:**
+
+After feed processing completes, parse the result document with type-safe data classes:
+
+```ruby
+# Get feed processing result document
+result_document = api.get_feed_document(result_feed_document_id)
+result_content = HTTP.get(result_document.dig("url")).to_s
+
+# Handle compression if needed
+if result_document.dig("compressionAlgorithm") == "GZIP"
+  require "zlib"
+  result_content = Zlib::GzipReader.new(StringIO.new(result_content)).read
+end
+
+# Parse with type safety
+result_json = JSON.parse(result_content)
+report = Peddler::Feeds::ListingsFeedProcessingReportSchema.parse(result_json)
+
+# Access structured processing results
+puts "Messages Processed: #{report.summary.messages_processed}"
+puts "Messages Accepted: #{report.summary.messages_accepted}"
+puts "Messages with Errors: #{report.summary.messages_with_error}"
+puts "Messages with Warnings: #{report.summary.messages_with_warning}"
+
+# Iterate through issues with type-safe access
+report.issues.each do |issue|
+  puts "\nIssue in message #{issue.message_id}:"
+  puts "  Severity: #{issue.severity}"
+  puts "  Code: #{issue.code}"
+  puts "  Message: #{issue.message}"
+  puts "  SKU: #{issue.sku}" if issue.sku
+end
+```
+
 #### Communication and Customer Management APIs
 
 - **Customer Feedback API (2024-06-01)**: Analyze customer reviews and returns data at item and browse node levels
@@ -458,6 +493,28 @@ destinations = sandbox_api.get_destinations
 subscription = sandbox_api.get_subscription("LISTINGS_ITEM_ISSUES_CHANGE")
 ```
 
+**Parsing Notifications:**
+
+Once you receive notifications (via SQS or EventBridge), parse them with type-safe data classes:
+
+```ruby
+# Parse notification from SQS message
+notification_json = JSON.parse(sqs_message.body)
+notification = Peddler::Notifications::AnyOfferChanged.parse(notification_json)
+
+# Type-safe access to notification data
+notification.notification_version  # => "1.0"
+notification.notification_type     # => "ANY_OFFER_CHANGED"
+
+# Access payload with autocomplete
+notification.payload.offers.each do |offer|
+  puts "Seller: #{offer.seller_id}"
+  puts "Price: #{offer.listing_price.amount} #{offer.listing_price.currency_code}"
+  puts "Condition: #{offer.item_condition}"
+  puts "Prime: #{offer.is_prime?}" if offer.respond_to?(:is_prime?)
+end
+```
+
 #### Vendor APIs
 
 APIs for vendors selling to Amazon:
@@ -654,6 +711,94 @@ response = api.download_report_document("DOCUMENT_ID")
 # Process the downloaded report content from response.body...
 ```
 
+#### Understanding Report Types
+
+SP-API provides two different types of reports with different formats and APIs:
+
+**1. Modern JSON-Based Reports** (Recommended)
+
+These are structured analytics reports that return JSON data with defined schemas. Peddler provides type-safe data classes for these reports using the Structure gem.
+
+Examples:
+- Vendor Real-Time Inventory Report
+- Seller Sales and Traffic Report
+- Account Health Report
+- Vendor Forecasting Report
+- Customer Feedback Reports
+
+Location in Peddler: `lib/peddler/reports/` with generated Structure-based classes
+
+```ruby
+# Example: Request and parse a vendor real-time inventory report
+api = Peddler.reports.new(aws_region, access_token)
+
+# Create report request
+report_response = api.create_report({
+  "reportType" => "GET_VENDOR_REAL_TIME_INVENTORY_REPORT",
+  "marketplaceIds" => [Marketplace.id("US")],
+  "reportOptions" => {
+    "reportPeriod" => "WEEK",
+    "distributorView" => "MANUFACTURING",
+    "sellingProgram" => "RETAIL",
+    "startDate" => "2024-01-01",
+    "endDate" => "2024-01-07"
+  }
+})
+
+# Wait for report to be ready, then download
+report_id = report_response.dig("reportId")
+# ... check status until DONE ...
+document_id = api.get_report(report_id).dig("reportDocumentId")
+
+# Download and parse JSON report
+document = api.get_report_document(document_id)
+report_json = HTTP.get(document.dig("url")).parse(:json)
+
+# Use typed data classes
+report = Peddler::Reports::VendorRealTimeInventory::Report.new(report_json)
+report.report_data.each do |data|
+  puts "ASIN: #{data.asin}, Inventory: #{data.highly_available_inventory}"
+end
+```
+
+**2. Legacy Flat-File Reports** (Tab-Delimited)
+
+These are older reports that return tab-delimited text files (TSV format), often GZIP compressed. These require manual CSV parsing and do NOT have Structure-based data classes.
+
+Examples:
+- `GET_MERCHANT_LISTINGS_ALL_DATA`
+- `GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA`
+- `GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL`
+
+These must be parsed manually using Ruby's CSV library:
+
+```ruby
+# Download flat-file report
+document = api.get_report_document(document_id)
+response = HTTP.get(document.dig("url"))
+
+# Handle GZIP compression if needed
+body = if document.dig("compressionAlgorithm") == "GZIP"
+         Zlib::GzipReader.new(StringIO.new(response.body.to_s)).read
+       else
+         response.body.to_s
+       end
+
+# Parse tab-delimited data
+csv_options = {
+  col_sep: "\t",
+  headers: true,
+  quote_char: "\x00",
+  encoding: "UTF-8"
+}
+CSV.parse(body, **csv_options) do |row|
+  # Process each row as a hash
+  puts "SKU: #{row['sku']}, ASIN: #{row['asin']}, Quantity: #{row['quantity']}"
+end
+```
+
+For a complete list of report types and their formats, see the [Report Type Values documentation](https://developer-docs.amazon.com/sp-api/docs/report-type-values).
+
 #### Sellers API
 
 ```ruby

data/lib/peddler/acronyms.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Peddler
+  # Handles acronym transformations for Amazon SP-API terminology
+  module Acronyms
+    extend self
+
+    # Mapping of camelized forms to their uppercase acronym equivalents
+    MAP = {
+      "Api" => "API",
+      "Asin" => "ASIN",
+      "B2b" => "B2B",
+      "Cgst" => "CGST",
+      "Cod" => "COD",
+      "Fba" => "FBA",
+      "Igst" => "IGST",
+      "Lwa" => "LWA",
+      "Safet" => "SAFET",
+      "Sgst" => "SGST",
+      "Sku" => "SKU",
+      "Tds" => "TDS",
+      "Url" => "URL",
+    }.freeze
+
+    # Transforms acronyms in camelized words to uppercase equivalents. Uses lookahead to prevent partial matches
+    # within words (e.g., "Cod" won't match inside "Code"). Handles singular and plural forms (e.g., "Apis" to "APIs").
+    #
+    # @param word [String]
+    # @return [String]
+    def apply(word)
+      MAP.reduce(word) { |w, (from, to)| w.gsub(/#{from}(s?)(?=[A-Z]|$)/) { "#{to}#{::Regexp.last_match(1)}" } }
+    end
+
+    # @return [Array<String>] Array of uppercase acronyms
+    def values
+      MAP.values
+    end
+  end
+end

data/lib/peddler/api.rb

@@ -3,12 +3,6 @@
 require "http"
 require "uri"
 
-require "peddler/endpoint"
-require "peddler/error"
-require "peddler/marketplace"
-require "peddler/response"
-require "peddler/version"
-
 module Peddler
   # Wraps an Amazon Selling Partner API (SP-API)
   class API

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/address.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Shipping address that represents the origin or destination location.
+      Address = Structure.new do
+        # @return [String] First line of the address text.
+        attribute(:address_line1, String, from: "addressLine1")
+
+        # @return [String] Two-digit, ISO 3166-1 alpha-2 formatted country code where this address is located.
+        attribute(:country_code, String, from: "countryCode")
+
+        # @return [String] Name of the person, business, or institution at this address.
+        attribute(:name, String)
+
+        # @return [String] State or region where this address is located. Note that this is contextual to the specified
+        # country code.
+        attribute(:state_or_region, String, from: "stateOrRegion")
+
+        # @return [String] Optional second line of the address text.
+        attribute?(:address_line2, String, from: "addressLine2")
+
+        # @return [String] Optional third line of the address text.
+        attribute?(:address_line3, String, from: "addressLine3")
+
+        # @return [String] Optional city where this address is located.
+        attribute?(:city, String)
+
+        # @return [String] Optional county where this address is located.
+        attribute?(:county, String)
+
+        # @return [String] Optional district where this address is located.
+        attribute?(:district, String)
+
+        # @return [String] Optional E.164-formatted phone number for an available contact at this address.
+        attribute?(:phone_number, String, from: "phoneNumber")
+
+        # @return [String] Optional postal code where this address is located.
+        attribute?(:postal_code, String, from: "postalCode")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/carrier_code.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Identifies the carrier that will deliver the shipment.
+      CarrierCode = Structure.new do
+        # @return [String] Denotes the carrier type.
+        attribute?(:carrier_code_type, String, from: "carrierCodeType")
+
+        # @return [String] Value of the carrier code.
+        attribute?(:carrier_code_value, String, from: "carrierCodeValue")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/destination_details.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Destination details of an inbound order based on the assigned region and DC for the order.
+      DestinationDetails = Structure.new do
+        # @return [Address] Destination address of the AWD facility where the shipment will be shipped to
+        attribute?(:destination_address, Address, from: "destinationAddress")
+
+        # @return [String] Assigned region where the order will be shipped. This can differ from what was passed as
+        # preference. AWD currently supports following region IDs: [us-west, us-east, us-southcentral, us-southeast]
+        attribute?(:destination_region, String, from: "destinationRegion")
+
+        # @return [String] Unique ID of the confirmed shipment being shipped to the assigned destination. This will be
+        # available only after an inbound order is confirmed and can be used to track the shipment.
+        attribute?(:shipment_id, String, from: "shipmentId")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/distribution_package.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents an AWD distribution package.
+      DistributionPackage = Structure.new do
+        # @return [DistributionPackageContents] The contents appropriate for the type.
+        attribute(:contents, DistributionPackageContents)
+
+        # @return [MeasurementData] Measurements of a package, including weight, volume, and dimensions.
+        attribute(:measurements, MeasurementData)
+
+        # @return [String] Type of distribution package.
+        attribute(:type, String)
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/distribution_package_contents.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents the contents inside a package, which can be products or a nested package.
+      DistributionPackageContents = Structure.new do
+        # @return [Array<DistributionPackageQuantity>] This is required only when `DistributionPackageType=PALLET`.
+        attribute?(:packages, [DistributionPackageQuantity])
+
+        # @return [Array<ProductQuantity>] This is required only when `DistributionPackageType=CASE`.
+        attribute?(:products, [ProductQuantity])
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/distribution_package_quantity.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents a distribution package with its respective quantity.
+      DistributionPackageQuantity = Structure.new do
+        # @return [Integer] Number of cases or pallets with the same package configuration.
+        attribute(:count, Integer)
+
+        # @return [DistributionPackage]
+        attribute(:distribution_package, "DistributionPackage", from: "distributionPackage")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Error response returned when the request is unsuccessful.
+      Error = Structure.new do
+        # @return [String] An error code that identifies the type of error that occurred.
+        attribute(:code, String)
+
+        # @return [String] A message that describes the error condition.
+        attribute(:message, String)
+
+        # @return [String] Additional details that can help the caller understand or fix the issue.
+        attribute?(:details, String)
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/error_list.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # This exception is thrown when client inputs are invalid.
+      ErrorList = Structure.new do
+        # @return [Array<Error>] A list of errors describing the failures.
+        attribute(:errors, [Error])
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/expiration_details.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+require "time"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # The expiration details of the inventory. This object will only appear if the details parameter in the request is
+      # set to `SHOW`.
+      ExpirationDetails = Structure.new do
+        # @return [Time] The expiration date of the SKU.
+        attribute?(:expiration, Time)
+
+        # @return [Integer] The quantity that is present in AWD.
+        attribute?(:onhand_quantity, Integer, from: "onhandQuantity")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_eligibility.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+require "time"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents the eligibility status of the inbound packages.
+      InboundEligibility = Structure.new do
+        # @return [Array<SkuEligibility>] Details on SKU eligibility for each inbound package.
+        attribute(:packages_to_inbound, [SKUEligibility], from: "packagesToInbound")
+
+        # @return [Time] Timestamp when the eligibility check is performed.
+        attribute(:previewed_at, Time, from: "previewedAt")
+
+        # @return [String]
+        attribute(:status, String)
+
+        # @return [Array<OrderIneligibilityReason>] If there are order level eligibility issues, then this list will
+        # contain those error codes and descriptions.
+        attribute?(:ineligibility_reasons, [OrderIneligibilityReason], from: "ineligibilityReasons")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_order.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+require "time"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents an AWD inbound order.
+      InboundOrder = Structure.new do
+        # @return [Time] Date when this order was created.
+        attribute(:created_at, Time, from: "createdAt")
+
+        # @return [String] Inbound order ID.
+        attribute(:order_id, String, from: "orderId")
+
+        # @return [String] Inbound order status.
+        attribute(:order_status, String, from: "orderStatus")
+
+        # @return [Address] Origin address from where the inbound order will be shipped.
+        attribute(:origin_address, Address, from: "originAddress")
+
+        # @return [Array<DistributionPackageQuantity>] List of packages to be inbounded.
+        attribute(:packages_to_inbound, [DistributionPackageQuantity], from: "packagesToInbound")
+
+        # @return [DestinationDetails] Destination details of an inbound order based on the assigned region and DC for
+        # the order.
+        attribute?(:destination_details, DestinationDetails, from: "destinationDetails")
+
+        # @return [String] Reference ID that can be used to correlate the order with partner resources.
+        attribute?(:external_reference_id, String, from: "externalReferenceId")
+
+        # @return [InboundPreferences]
+        attribute?(:preferences, InboundPreferences)
+
+        # @return [Time] Date when this order was last updated.
+        attribute?(:updated_at, Time, from: "updatedAt")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_order_creation_data.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Payload for creating an inbound order.
+      InboundOrderCreationData = Structure.new do
+        # @return [Address] Origin address from where the inbound order will be shipped.
+        attribute(:origin_address, Address, from: "originAddress")
+
+        # @return [Array<DistributionPackageQuantity>] List of packages to be inbounded.
+        attribute(:packages_to_inbound, [DistributionPackageQuantity], from: "packagesToInbound")
+
+        # @return [String] Reference ID that can be used to correlate the order with partner resources.
+        attribute?(:external_reference_id, String, from: "externalReferenceId")
+
+        # @return [InboundPreferences]
+        attribute?(:preferences, InboundPreferences)
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_order_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # A response that contains the reference identifiers for the newly created or updated inbound order. Consists of
+      # an order ID and version.
+      InboundOrderReference = Structure.new do
+        # @return [String] Order ID of the inbound order.
+        attribute(:order_id, String, from: "orderId")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_packages.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Represents the packages to inbound.
+      InboundPackages = Structure.new do
+        # @return [Array<DistributionPackageQuantity>] List of packages to be inbounded.
+        attribute(:packages_to_inbound, [DistributionPackageQuantity], from: "packagesToInbound")
+      end
+    end
+  end
+end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09/inbound_preferences.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# This file is generated. Do not edit.
+
+require "structure"
+
+module Peddler
+  module APIs
+    class AmazonWarehousingAndDistribution20240509
+      # Preferences that can be passed in context of an inbound order
+      InboundPreferences = Structure.new do
+        # @return [String] Pass a preferred region so that the inbound order can be shipped to an AWD warehouse located
+        # in that region. This doesn't guarantee the order to be assigned in the specified destination region as it
+        # depends on warehouse capacity availability. AWD currently supports following region IDs: [us-west, us-east,
+        # us-southcentral, us-southeast]
+        attribute?(:destination_region, String, from: "destinationRegion")
+      end
+    end
+  end
+end