peddler 4.3.1 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfb5b2595fa619d422cd487a9c07a54659a5152d4e2168abf69af45ec98fff68
-  data.tar.gz: 1c950c5f13fe1837c36d6035b4e36ffe9c28687a3425fb5db753cd5bf0b72edf
+  metadata.gz: 747dd42d445c711adc43f20e6a9c479bf795352512fecc67814f1a5f698c86a9
+  data.tar.gz: 134255293900b9c32086f2291a42498e1477f29df64cbe0aa8b3da1420dfe320
 SHA512:
-  metadata.gz: 8cc66a461269368582b15cef95c2209d9fe1c969cad00a58ab6d7d7a7771540686baa919b8067aa447de6b47f1543206929a7e47a403f74d3efbdc8cfe9a0cc5
-  data.tar.gz: c93c7d80ebbc031cdf8c4a02e58f10878745e461b129260b442cc5eaf3de36c219cd56756573aec55976824aa4d7ed243e044b5ef5d89af7039a4cade3fec187
+  metadata.gz: 5880a513c77e79ae8523ca96c69d65697c179ede0febc18f2b4a10d932e7de9ed32cdf74c82ff13bc68ca7c15ae6df9d84ec92150d7bc018da6778e104dcb889
+  data.tar.gz: 60b00292980fdac6da6acccac237b0ce677f7e49cb001f72584426aa70d54deac3c84d9e89abc5e380cf94aecda6db0d695d39868644380acb8c86603245e30d

data/README.md

@@ -11,7 +11,7 @@ To begin using the Amazon SP-API, you must [register as a developer][register-as
 - [API models][api-models]
 - [API samples][api-samples]
 
-![Peddler](https://github.com/hakanensari/peddler/blob/main/images/peddler.jpg?raw=true)
+<img src="https://github.com/hakanensari/peddler/blob/main/images/peddler.jpg?raw=true" alt="Peddler" style="max-width: 830px" />
 
 ## Installation
 
@@ -120,124 +120,89 @@ Peddler provides Ruby interfaces to all Amazon SP-API endpoints. Each API is ava
 api = Peddler.<api_name>_<version>(aws_region, access_token, options)
 ```
 
-Below are key APIs with examples of their usage:
-
-#### Orders API (v0)
-
-Retrieve order information and manage orders.
+You can also simply initialize the latest version:
 
 ```ruby
-api = Peddler.orders_v0(aws_region, access_token)
-response = api.get_orders(
-  marketplaceIds: ["ATVPDKIKX0DER"],
-  createdAfter: "2023-01-01T00:00:00Z"
-)
-orders = response.parse["orders"]
+api = Peddler.<api_name>(aws_region, access_token, options)
 ```
 
-#### Catalog Items API (2022-04-01, 2020-12-01, v0)
-
-Access Amazon's catalog data including product details, offers, and competitive pricing.
-
-```ruby
-api = Peddler.catalog_items_2022_04_01(aws_region, access_token)
-response = api.get_catalog_item(
-  marketplaceIds: ["ATVPDKIKX0DER"],
-  asin: "B08N5WRWNW"
-)
-item_details = response.parse["payload"]
-```
+Below is a comprehensive list of all available APIs organized by category:
 
-#### Feeds API (2021-06-30)
+#### Orders and Financial APIs
 
-Upload data to Amazon to update listings, prices, inventory, and more.
+- **Orders API (v0)**: Retrieve and manage orders
+- **Finances API (2024-06-19, 2024-06-01, v0)**: Get financial data including transaction details, payments, and refunds
+- **Invoices API (2024-06-19)**: Manage billing invoices
+- **Sales API (v1)**: Get order metrics and sales data
 
 ```ruby
-api = Peddler.feeds_2021_06_30(aws_region, access_token)
-
-# Create feed document
-document_response = api.create_feed_document(
-  contentType: "text/xml; charset=UTF-8"
-)
-feed_document_id = document_response.parse["feedDocumentId"]
-upload_url = document_response.parse["url"]
-
-# Upload feed content
-feed_content = File.read("inventory_update.xml")
-api.upload_feed_document(upload_url, feed_content, "text/xml; charset=UTF-8")
-
-# Create feed
-feed_response = api.create_feed(
-  feedType: "POST_INVENTORY_AVAILABILITY_DATA",
+api = Peddler.orders(aws_region, access_token)
+response = api.get_orders(
   marketplaceIds: ["ATVPDKIKX0DER"],
-  inputFeedDocumentId: feed_document_id
+  createdAfter: "2023-01-01T00:00:00Z"
 )
-feed_id = feed_response.parse["feedId"]
-```
 
-#### Reports API (2021-06-30)
+# Use the `dig` method to safely navigate through nested response data
+# This returns nil instead of raising an error if any key in the path doesn't exist
+orders = response.dig("payload", "orders")
 
-Request and download reports about orders, inventory, fulfillment, and more.
+# You can chain multiple keys to access deeply nested data
+first_order_id = response.dig("payload", "orders", 0, "amazonOrderId")
 
-```ruby
-api = Peddler.reports_2021_06_30(aws_region, access_token)
+# This is safer than using chain indexing which would raise an error if any part is missing:
+# response.parse["payload"]["orders"][0]["amazonOrderId"]  # Error prone!
 
-# Request a report
-create_response = api.create_report(
-  reportType: "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
-  marketplaceIds: ["ATVPDKIKX0DER"]
+# For sandbox testing
+api.sandbox.get_orders(
+  marketplaceIds: ["ATVPDKIKX0DER"],
+  createdAfter: "TEST_CASE_200"
 )
-report_id = create_response.parse["reportId"]
-
-# Check report status
-report = api.get_report(report_id).parse
-
-# Once processed, get the document
-if report["processingStatus"] == "DONE"
-  doc_id = report["reportDocumentId"]
-  document = api.get_report_document(doc_id).parse
-  download_url = document["url"]
-  # Download report from URL
-end
 ```
 
-#### Listings APIs
-
-Manage product listings with multiple APIs:
+#### Catalog and Listing APIs
 
+- **Catalog Items API (2022-04-01, 2020-12-01, v0)**: Access Amazon's catalog data
 - **Listings Items API (2021-08-01, 2020-09-01)**: Create and update listings
 - **Listings Restrictions API (2021-08-01)**: Check listing eligibility
 - **Product Type Definitions API (2020-09-01)**: Get schema requirements for listings
+- **A+ Content API (2020-11-01)**: Create and manage enhanced marketing content
+- **Product Pricing API (2022-05-01, v0)**: Get pricing information
+- **Product Fees API (v0)**: Retrieve fee estimates for products
 
 ```ruby
-api = Peddler.listings_items_2021_08_01(aws_region, access_token)
-api.put_listings_item(
-  seller_id,
-  "SKU123",
-  "ATVPDKIKX0DER",
-  body: {
-    productType: "LUGGAGE",
-    requirements: "LISTING",
-    attributes: {
-      title: [{ value: "Travel Backpack" }],
-      manufacturer: [{ value: "Brand Name" }]
-    }
-  }
+api = Peddler.catalog_items(aws_region, access_token)
+response = api.get_catalog_item(
+  marketplaceIds: ["ATVPDKIKX0DER"],
+  asin: "B08N5WRWNW"
 )
-```
+item_details = response.dig("payload")
 
-#### Fulfillment APIs
+# Search catalog items by identifier
+response = api.search_catalog_items(
+  ["ATVPDKIKX0DER"],
+  identifiers: "B08N5WRWNW",
+  identifiers_type: "ASIN"
+)
+search_results = response.parse
+```
 
-Manage inventory and fulfillment through FBA and merchant fulfillment:
+#### Fulfillment and Inventory APIs
 
 - **Fulfillment Inbound API (2024-03-20, v0)**: Send inventory to FBA
 - **Fulfillment Outbound API (2020-07-01)**: Create and track FBA orders
 - **FBA Inventory API (v1)**: Manage FBA inventory quantities
+- **FBA Inbound Eligibility API (v1)**: Check product eligibility for FBA
 - **Merchant Fulfillment API (v0)**: Create shipping labels for self-fulfilled orders
+- **Easy Ship API (2022-03-23)**: Manage Amazon's carrier service for deliveries
+- **Shipping APIs (v1, v2)**: Create shipments and purchase shipping labels
+- **Replenishment API (2022-11-07)**: Manage inventory replenishment
+- **Amazon Warehousing and Distribution API (2024-05-09)**: Manage fulfillment warehousing
+- **Supply Sources API (2020-07-01)**: Manage supply/inventory sources
+- **Shipment Invoicing API (v0)**: Manage shipment-related invoices
 
 ```ruby
 # FBA outbound example
-api = Peddler.fulfillment_outbound_2020_07_01(aws_region, access_token)
+api = Peddler.fulfillment_outbound(aws_region, access_token)
 api.create_fulfillment_order(
   body: {
     sellerFulfillmentOrderId: "ORDER123",
@@ -263,24 +228,94 @@ api.create_fulfillment_order(
 )
 ```
 
-#### Financial APIs (2024-06-19, 2024-06-01, v0)
+#### Data Management APIs
 
-Get financial data including transaction details, payments, and refunds.
+- **Feeds API (2021-06-30)**: Upload data to Amazon to update listings, prices, inventory, and more
+- **Reports API (2021-06-30)**: Request and download reports about orders, inventory, fulfillment, and more
+- **Uploads API (2020-11-01)**: Upload files for various SP-API operations
+- **Data Kiosk API (2023-11-15)**: Access and manage analytical data
 
 ```ruby
-api = Peddler.finances_v0(aws_region, access_token)
-response = api.list_financial_events(
-  posted_after: "2023-01-01T00:00:00Z"
+api = Peddler.feeds(aws_region, access_token)
+
+# Create feed document
+document_response = api.create_feed_document(
+  contentType: "text/xml; charset=UTF-8"
+)
+
+# The `dig` method safely navigates the response hash
+# If the response structure is:
+# {
+#   "feedDocumentId": "amzn1.tortuga.3.abc123...",
+#   "url": "https://s3.amazonaws.com/bucket/key...",
+#   "encryptionDetails": {
+#     "standard": "AES",
+#     "key": "encryption-key",
+#     "initializationVector": "vector-value"
+#   }
+# }
+
+# Access top-level keys with dig
+feed_document_id = document_response.dig("feedDocumentId")
+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
+feed_content = File.read("inventory_update.xml")
+api.upload_feed_document(upload_url, feed_content, "text/xml; charset=UTF-8")
+
+# Create feed
+feed_response = api.create_feed(
+  feedType: "POST_INVENTORY_AVAILABILITY_DATA",
+  marketplaceIds: ["ATVPDKIKX0DER"],
+  inputFeedDocumentId: feed_document_id
+)
+feed_id = feed_response.dig("feedId")
+
+# Upload JSON feed
+json_document = api.create_feed_document(
+  { "contentType" => "application/json; charset=UTF-8" }
 )
-financial_events = response.parse["FinancialEvents"]
+json_feed_content = JSON.generate({
+  "header": {
+    "sellerId": "SELLER_ID",
+    "version": "2.0",
+    "issueLocale": "en_US"
+  },
+  "messages": [
+    {
+      "messageId": 1,
+      "sku": "SKU123",
+      "operationType": "UPDATE",
+      "productType": "PRODUCT",
+      "attributes": {
+        # Your product attributes here
+      }
+    }
+  ]
+})
+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"
 ```
 
-#### Notifications API (v1)
+#### Communication and Customer Management APIs
 
-Subscribe to notifications for various events like order updates and report processing.
+- **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
-api = Peddler.notifications_v1(aws_region, access_token)
+api = Peddler.notifications(aws_region, access_token)
 # Create destination
 destination = api.create_destination(
   name: "MyEventQueue",
@@ -288,7 +323,7 @@ destination = api.create_destination(
     sqs: { arn: "arn:aws:sqs:us-east-1:123456789012:MyQueue" }
   }
 )
-destination_id = destination.parse["payload"]["destinationId"]
+destination_id = destination.dig("payload", "destinationId")
 
 # Create subscription
 api.create_subscription(
@@ -296,6 +331,14 @@ api.create_subscription(
   destinationId: destination_id,
   payloadVersion: "1"
 )
+
+# For sandbox testing (requires grantless token)
+sandbox_api = Peddler.notifications(aws_region, grantless_access_token).sandbox
+# Get all destinations
+destinations = sandbox_api.get_destinations
+
+# Get specific subscription
+subscription = sandbox_api.get_subscription("LISTINGS_ITEM_ISSUES_CHANGE")
 ```
 
 #### Vendor APIs
@@ -303,36 +346,212 @@ api.create_subscription(
 APIs for vendors selling to Amazon:
 
 - **Vendor Orders API (v1)**: Retrieve purchase orders
-- **Vendor Direct Fulfillment APIs**: Manage orders, shipping, payments, and inventory
+- **Vendor Direct Fulfillment Orders API (2021-12-28, v1)**: Manage direct fulfillment orders
+- **Vendor Direct Fulfillment Shipping API (2021-12-28, v1)**: Manage shipping for direct fulfillment
+- **Vendor Direct Fulfillment Payments API (v1)**: Process payments for direct fulfillment
+- **Vendor Direct Fulfillment Inventory API (v1)**: Manage inventory for direct fulfillment
+- **Vendor Direct Fulfillment Transactions API (2021-12-28, v1)**: Track transaction status
+- **Vendor Direct Fulfillment Sandbox Test Data API (2021-10-28)**: Generate test data in sandbox
 - **Vendor Shipments API (v1)**: Track vendor shipments
 - **Vendor Invoices API (v1)**: Submit and track invoices
+- **Vendor Transaction Status API (v1)**: Check transaction status
 
 ```ruby
-api = Peddler.vendor_orders_v1(aws_region, access_token)
+api = Peddler.vendor_orders(aws_region, access_token)
 orders = api.get_purchase_orders(
   limit: 10,
   createdAfter: "2023-01-01T00:00:00Z"
 ).parse
 ```
 
-#### Additional APIs
+#### Authorization and Account Management APIs
 
-- **A+ Content API (2020-11-01)**: Create and manage enhanced marketing content
-- **Authorization API (2023-11-30)**: Manage app authorization
-- **Messaging API (v1)**: Send messages to customers
-- **Product Fees API (v0)**: Retrieve fee estimates for products
-- **Product Pricing API (2022-05-01, v0)**: Get pricing information
-- **Sellers API (v1)**: Get seller account information and marketplace participation
-- **Shipping APIs (v1, v2)**: Create shipments and purchase shipping labels
-- **Solicitations API (v1)**: Request customer reviews
+- **Application Management API (2023-11-30)**: Manage application authorization
 - **Tokens API (2021-03-01)**: Generate restricted data tokens for accessing PII
-- **Uploads API (2020-11-01)**: Upload files for various SP-API operations
+- **Sellers API (v1)**: Get seller account information and marketplace participation
+- **Services API (v1)**: Manage seller services and subscriptions
+- **Seller Wallet API (2024-03-01)**: Manage seller financial accounts
+- **Application Integrations API (2024-04-01)**: Manage app integrations
+- **Vehicles API (2024-11-01)**: Manage vehicle data for automotive products
+
+### Additional API Examples
+
+#### Product Pricing API
+
+```ruby
+# Using Product Pricing v0
+api = Peddler.product_pricing_v0(aws_region, access_token)
+
+# Get pricing information for an ASIN
+pricing = api.get_pricing(
+  Marketplace.id("US"),
+  "Asin",
+  asins: ["B08N5WRWNW"]
+)
+
+# Get competitive pricing for an ASIN
+competitive = api.get_competitive_pricing(
+  Marketplace.id("US"),
+  "Asin",
+  asins: ["B08N5WRWNW"]
+)
+
+# Get offers for a specific item
+offers = api.get_item_offers(
+  Marketplace.id("US"),
+  "New",
+  "B08N5WRWNW"
+)
+
+# Batch request for multiple items (2022-05-01 API)
+api = Peddler.product_pricing_2022_05_01(aws_region, access_token)
+batch_request = {
+  requests: [
+    {
+      uri: "/products/pricing/2022-05-01/items/competitiveSummary",
+      method: "GET",
+      asin: "B08N5WRWNW",
+      marketplaceId: Marketplace.id("US"),
+      includedData: ["featuredBuyingOptions", "referencePrices", "lowestPricedOffers"]
+    },
+    # Additional items...
+  ]
+}
+results = api.get_competitive_summary(batch_request)
+```
+
+#### Listings Items API
+
+```ruby
+api = Peddler.listings_items(aws_region, access_token)
+
+# Create or update a listing
+listing_result = api.put_listings_item(
+  "SELLER_ID",
+  "SKU123",
+  Marketplace.id("US"),
+  {
+    productType: "PRODUCT",
+    requirements: "LISTING_OFFER_ONLY",
+    attributes: {
+      merchant_suggested_asin: [{
+        value: "B08N5WRWNW",
+        marketplace_id: Marketplace.id("US")
+      }],
+      condition_type: [{
+        value: "new_new",
+        marketplace_id: Marketplace.id("US")
+      }],
+      # Additional attributes...
+    }
+  }
+)
+
+# Update specific listing elements with JSON Patch
+patch_result = api.patch_listings_item(
+  "SELLER_ID",
+  "SKU123",
+  Marketplace.id("US"),
+  {
+    productType: "PRODUCT",
+    patches: [
+      {
+        op: "replace",
+        path: "/attributes/purchasable_offer",
+        value: [{
+          currency: "USD",
+          our_price: [{
+            schedule: [{
+              value_with_tax: 39.99
+            }]
+          }]
+        }]
+      }
+    ]
+  }
+)
+
+# Get listing details
+listing = api.get_listings_item(
+  "SELLER_ID",
+  "SKU123",
+  Marketplace.id("US"),
+  included_data: "attributes,issues"
+)
+
+# Delete a listing
+api.delete_listings_item("SELLER_ID", "SKU123", Marketplace.id("US"))
+```
+
+#### Listings Restrictions API
+
+```ruby
+api = Peddler.listings_restrictions(aws_region, access_token)
+
+# Check restrictions for an ASIN
+restrictions = api.get_listings_restrictions(
+  "B08N5WRWNW",
+  "SELLER_ID",
+  Marketplace.id("US"),
+  condition_type: "new_new"
+)
+```
+
+#### Product Type Definitions API
+
+```ruby
+api = Peddler.product_type_definitions(aws_region, access_token)
+
+# Get schema for a product type
+definition = api.get_definitions_product_type(
+  "PRODUCT",
+  Marketplace.id("US"),
+  requirements: "LISTING_OFFER_ONLY"
+)
+
+# Download the JSON schema
+schema_url = definition.dig("schema", "link", "resource")
+json_schema = HTTP.get(schema_url).parse(:json)
+```
+
+#### Reports API
+
+```ruby
+api = Peddler.reports(aws_region, access_token)
+
+# Request a report
+report_response = api.create_report({
+  "reportType" => "GET_MERCHANTS_LISTINGS_FYP_REPORT",
+  "marketplaceIds" => Marketplace.ids("US")
+})
+report_id = report_response.dig("reportId")
+
+# Get report status
+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...
+```
+
+#### Sellers API
+
+```ruby
+api = Peddler.sellers(aws_region, access_token)
+
+# Get marketplace participations
+participations = api.get_marketplace_participations
+```
 
-For a complete list of available APIs, refer to the [API models repository](https://github.com/amzn/selling-partner-api-models).
+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
+- [ ] Code generate payload parsers 🤔
 - [ ] Review and consider applying [these patches][patches]
 
 [build]: https://github.com/hakanensari/peddler/actions

data/lib/peddler/api.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "http"
+require "uri"
 
 require "peddler/endpoint"
 require "peddler/error"
@@ -158,5 +159,15 @@ module Peddler
     def timestamp
       Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
     end
+
+    # Encodes URL path components
+    def percent_encode(component)
+      URI.encode_uri_component(component)
+    end
+
+    # Converts an array to a comma-separated string, or returns the value as-is if not an array
+    def stringify_array(val)
+      val.is_a?(Array) ? val.join(",") : val
+    end
   end
 end

data/lib/peddler/apis/amazon_warehousing_and_distribution_2024_05_09.rb

@@ -35,7 +35,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def get_inbound(order_id, rate_limit: 2.0)
-        path = "/awd/2024-05-09/inboundOrders/#{order_id}"
+        path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}"
 
         meter(rate_limit).get(path)
       end
@@ -49,7 +49,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def update_inbound(order_id, body, rate_limit: 1.0)
-        path = "/awd/2024-05-09/inboundOrders/#{order_id}"
+        path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}"
 
         meter(rate_limit).put(path, body:)
       end
@@ -61,7 +61,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def cancel_inbound(order_id, rate_limit: 1.0)
-        path = "/awd/2024-05-09/inboundOrders/#{order_id}/cancellation"
+        path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}/cancellation"
 
         meter(rate_limit).post(path)
       end
@@ -73,7 +73,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def confirm_inbound(order_id, rate_limit: 1.0)
-        path = "/awd/2024-05-09/inboundOrders/#{order_id}/confirmation"
+        path = "/awd/2024-05-09/inboundOrders/#{percent_encode(order_id)}/confirmation"
 
         meter(rate_limit).post(path)
       end
@@ -87,7 +87,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @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}"
+        path = "/awd/2024-05-09/inboundShipments/#{percent_encode(shipment_id)}"
         params = {
           "skuQuantities" => sku_quantities,
         }.compact
@@ -106,7 +106,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @return [Peddler::Response] The API response
       def get_inbound_shipment_labels(shipment_id, page_type: nil, format_type: nil, rate_limit: 1.0)
-        path = "/awd/2024-05-09/inboundShipments/#{shipment_id}/labels"
+        path = "/awd/2024-05-09/inboundShipments/#{percent_encode(shipment_id)}/labels"
         params = {
           "pageType" => page_type,
           "formatType" => format_type,
@@ -123,7 +123,7 @@ module Peddler
       # @param rate_limit [Float] Requests per second
       # @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/#{shipment_id}/transport"
+        path = "/awd/2024-05-09/inboundShipments/#{percent_encode(shipment_id)}/transport"
 
         meter(rate_limit).put(path, body:)
       end