peddler 3.0.0.beta1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f132e3d74dc1f70f5f0d84f84cc75e6d4e9184bd2ed4162e2e805a766341afed
-  data.tar.gz: 65c57dc08f0d1e1b23f87969ec2657d7592ea4590c65d3c18b7e9c9ac612ed71
+  metadata.gz: 18b989739aa0f7ab2781e4f2f921b61a6f188ffc72145eb9308e47d3f5072e96
+  data.tar.gz: 0ea9798e14b2e7474fef0c8b492d43e90d427fee962d4f837fc46722750733b8
 SHA512:
-  metadata.gz: cc5e82f24bd72cebd6d226e713d22e792944e043489da3a7f79245fd5242f1430cef84201643e9ebd5a25d9b5a10c9bbf5ae88e70f27a4d52a7b077482f9760a
-  data.tar.gz: 80a16515b74499a28513058b41eab6a912bcb21249d7748cedd74db9efd7e3ccc2316e896f78b9406c2e1f7d078b667ad73a62a980054cd0982135a9b219fd0f
+  metadata.gz: 9acfcab4a74ef4842c1cb28e94b1a57591caba5080e07a6db34d8f20f69b0d215efdcfb98761fefeaf840cb4a0c91cc574807651c8beb309dbfc91ad66502b05
+  data.tar.gz: 281d96aa87b0ea0c480282049124c8ed3037e4a31ef8251b7a6cc3e8c17acbb53e8253a41f248a6e3a95eea7c6d3363d740e0d23dffe2b6e1caaf82bbbdbea09

data/README.md

@@ -6,7 +6,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.
 
-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 on Amazon][view-credentials]. You'll use these to access data for your own seller account or retrieve data on behalf of others.
+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.
 
 ![Peddler](https://github.com/hakanensari/peddler/blob/main/images/peddler.jpg?raw=true)
 
@@ -39,53 +39,65 @@ Require the library.
 require "peddler"
 ```
 
-### Authentication
+### Authorization
 
-A seller or vendor will [provide a refresh token][authorization] to access their data on Amazon. You'll use this to generate temporary access tokens to authenticate individual API requests. Here’s how you can request one in Peddler.
+A seller or vendor [provides you a refresh token][authorization] to access their data on Amazon.
 
 ```ruby
-access_token = Peddler::AccessToken.request(
+refresh_token = Peddled::Token.request(
+  code: "<AUTHORIZATION_CODE>"
+).parse["refresh_token"]
+```
+
+You use this to generate a temporary access token to authenticate individual API requests.
+
+```ruby
+access_token = Peddler::Token.request(
   refresh_token: "<REFRESH_TOKEN>",
-)
+).parse["access_token"]
 ```
 
-You can also request a token for grantless operations.
+Similarly, you can request a token for grantless operations.
 
 ```ruby
-access_token = Peddler::AccessToken.request(
+access_token = Peddler::Token.request(
   scope: "sellingpartnerapi::notifications",
-)
+).parse["access_token"]
 ```
 
-Access tokens are valid for one hour. To optimize performance, cache the token and reuse it across calls instead of generating a new one each time.
-
-If you haven’t set your LWA credentials as environment variables, you can pass them directly when requesting an access token:
+If you haven’t set your LWA credentials as environment variables, pass them directly when requesting the token.
 
 ```ruby
-access_token = Peddler::AccessToken.request(
+access_token = Peddler::Token.request(
   client_id: "<YOUR_CLIENT_ID>",
   client_secret: "<YOUR_CLIENT_SECRET>",
   refresh_token: "<REFRESH_TOKEN>",
-)
+).parse["access_token"]
 ```
 
-### Throttling
+Access tokens are valid for one hour. To optimize performance, cache the token and reuse across calls.
 
-Amazon’s Selling Partner API (SP-API) imposes standard rate limits on most operations. Peddler respects these limits and automatically backs off when throttled to ensure compliance with Amazon’s policies.
-
-**Note:** This functionality requires version 6 of the underlying [HTTP library][httprb]. As of writing, this is not released yet. To use rate limiting, point to the main branch of their GitHub repo:
+In Rails, if you're storing a refresh token in a model representing a selling partner, implement a method there to retrieve and cache access tokens:
 
 ```ruby
-gem "http", github: "httprb/http"
+class Seller
+  "..."
+
+  def access_token
+    Rails.cache.fetch("#{cache_key}/access_key", expires_in: 1.hour) do
+      Peddler::Token.request(
+        refresh_token:,
+      ).parse["access_token"]
+    end
+  end
+end
 ```
 
-If you have custom rate limits (e.g., Amazon has granted you higher quotas), you can override the standard rate limit using the rate_limit method.
+### Rate limiting
 
-```ruby
-@api.rate_limit(5).get_item_offers_batch(...)
-```
+Amazon’s Selling Partner API (SP-API) imposes [rate limits][rate-limits] on most operations. Peddler respects these limits and automatically backs off when throttled. To override the default rate limit, pass a `:rate_limit` argument when running an operation.
 
-This sets a custom rate limit of 5 requests per second for the requested operation.
+**Note:** This functionality requires version 6 of the underlying [HTTP library][httprb]. As of writing, this is not released yet. To use rate limiting, point to their main branch on GitHub.
 
 ### The APIs
 
@@ -95,11 +107,9 @@ Peddler provides a class for each API version under an eponymous namespace. Belo
 
 Provides programmatic access to Amazon's catalog data, such as item titles, descriptions, and other product details.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::CatalogItems20220401.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_catalog_item(
+api = Peddler.catalog_items_2022_04_01(aws_region, access_token)
+response = api.get_catalog_item(
   marketplaceIds: ["ATVPDKIKX0DER"],
   asin: "B08N5WRWNW"
 )
@@ -110,27 +120,24 @@ items = response.parse.dig("items")
 
 Allows you to retrieve order information, including order details, buyer information, and order items.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::OrdersV0.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_orders(
+api = Peddler.orders_v0(aws_region, access_token)
+response = api.get_orders(
   marketplaceIds: ["ATVPDKIKX0DER"],
   createdAfter: "2023-01-01T00:00:00Z"
 )
-orders = response.parse.dig("orders")
+response.parse.dig("orders")
 ```
 
 #### Feeds API (2021-06-30)
 
 Enables you to upload data to Amazon for updating listings, prices, inventory, and more.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::Feeds20210630.new("<AWS_REGION>", "<ACCESS_TOKEN>")
+api = Peddler.feeds_2021_06_30(aws_region, access_token)
+
 # Create a feed document to get an upload URL
-response = client.create_feed_document(
+response = api.create_feed_document(
   contentType: "text/xml; charset=UTF-8"
 )
 feed_document_id = response.parse["feedDocumentId"]
@@ -138,41 +145,37 @@ upload_url = response.parse["url"]
 
 # Upload the feed content to the provided URL
 feed_content = File.read("inventory_update.xml")
-client.upload_feed_document(upload_url, feed_content)
+api.upload_feed_document(upload_url, feed_content)
 
 # Create the feed
-response = client.create_feed(
+response = api.create_feed(
   feedType: "POST_INVENTORY_AVAILABILITY_DATA",
   marketplaceIds: ["ATVPDKIKX0DER"],
   inputFeedDocumentId: feed_document_id
 )
-feed_id = response.parse["feedId"]
+response.parse["feedId"]
 ```
 
 #### Reports API (2021-06-30)
 
 Allows you to request and download various reports, such as order and inventory reports.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::Reports20210630.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.create_report(
+api = Peddler.reports_2021_06_30(aws_region, access_token)
+response = api.create_report(
   reportType: "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
   marketplaceIds: ["ATVPDKIKX0DER"]
 )
-report_id = response.parse["reportId"]
+response.parse["reportId"]
 ```
 
 #### Listings Items API (2021-08-01)
 
 Enables you to manage your product listings on Amazon, including creating, updating, and deleting listings.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::ListingsItems20210801.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.put_listings_item(
+api = Peddler.listings_items_2021_08_01(aws_region, access_token)
+response = api.put_listings_item(
   "<SELLER_ID>",
   "SKU123",
   "ATVPDKIKX0DER",
@@ -187,19 +190,17 @@ response = client.put_listings_item(
     }
   }
 )
-result = response.parse
+response.parse
 ```
 
 #### Notifications API (v1)
 
 Allows you to subscribe to notifications for specific events like order status updates or feed processing statuses.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::NotificationsV1.new("<AWS_REGION>", "<ACCESS_TOKEN>")
+api = Peddler.notifications_v1(aws_region, access_token)
 # Create a destination
-response = client.create_destination(
+response = api.create_destination(
   name: "MySQSQueue",
   resourceSpecification: {
     sqs: {
@@ -210,7 +211,7 @@ response = client.create_destination(
 destination_id = response.parse["destinationId"]
 
 # Create a subscription
-response = client.create_subscription(
+response = api.create_subscription(
   notificationType: "ANY_OFFER_CHANGED",
   destinationId: destination_id
 )
@@ -221,11 +222,9 @@ subscription = response.parse
 
 Provides information about fees that may be charged for selling products on Amazon.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::ProductFeesV0.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_my_fees_estimate_for_sku(
+api = Peddler.product_fees_v0(aws_region, access_token)
+response = api.get_my_fees_estimate_for_sku(
   sellerId: "<YOUR_SELLER_ID>",
   sku: "SKU123",
   body: {
@@ -248,11 +247,9 @@ fees_estimate = response.parse
 
 Allows you to create and manage fulfillment orders using Amazon's fulfillment network.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::FulfillmentOutbound20200701.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.create_fulfillment_order(
+api = Peddler.fulfillment_outbound_2020_07_01(aws_region, access_token)
+response = api.create_fulfillment_order(
   body: {
     sellerFulfillmentOrderId: "ORDER123",
     displayableOrderId: "ORDER123",
@@ -276,18 +273,16 @@ response = client.create_fulfillment_order(
     ]
   }
 )
-result = response.parse
+response.parse
 ```
 
 #### Merchant Fulfillment API (v0)
 
 Allows you to create shipping labels for orders using Amazon's negotiated shipping rates.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::MerchantFulfillmentV0.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_eligible_shipping_services(
+api = Peddler.merchant_fulfillment_v0(aws_region, access_token)
+response = api.get_eligible_shipping_services(
   body: {
     shipmentRequestDetails: {
       amazonOrderId: "ORDER123",
@@ -329,11 +324,9 @@ shipping_services = response.parse["shippingServiceList"]
 
 Allows vendors to retrieve purchase orders and order details from Amazon.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::VendorOrders20211228.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_purchase_orders(
+api = Peddler.vendor_orders_2021_12_28(aws_region, access_token)
+response = api.get_purchase_orders(
   shipToPartyId: "<PARTY_ID>",
   limit: 10,
   createdAfter: "2023-01-01T00:00:00Z"
@@ -345,40 +338,36 @@ purchase_orders = response.parse["purchaseOrders"]
 
 Enables vendors to manage shipping labels and shipping information for direct fulfillment orders.
 
-**Example:**
 
 ```ruby
-client = Peddler::API::VendorDirectFulfillmentShipping20211228.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_packing_slip(
+api = Peddler.vendor_direct_fulfillment_shipping_2021_12_28(aws_region, access_token)
+response = api.get_packing_slip(
   purchaseOrderNumber: "PO123456789"
 )
-packing_slip = response.parse
+response.parse
 ```
 
 #### Vendor Direct Fulfillment Orders API (2021-12-28)
 
 Allows vendors to receive orders for direct fulfillment and provide shipment confirmations.
 
-**Example:**
 
 ```ruby
-client = Peddler::API::VendorDirectFulfillmentOrders20211228.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.get_orders(
+api = Peddler.vendor_direct_fulfillment_orders_2021_12_28(aws_region, access_token)
+response = api.get_orders(
   createdAfter: "2023-01-01T00:00:00Z",
   limit: 10
 )
-orders = response.parse["orders"]
+response.parse["orders"]
 ```
 
 #### Vendor Direct Fulfillment Inventory API (2021-12-28)
 
 Enables vendors to update inventory levels for direct fulfillment items.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::VendorDirectFulfillmentInventory20211228.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.submit_inventory_update(
+api = Peddler.vendor_direct_fulfillment_inventory_2021_12_28(aws_region, access_token)
+response = api.submit_inventory_update(
   body: {
     inventory: [
       {
@@ -399,18 +388,16 @@ response = client.submit_inventory_update(
     ]
   }
 )
-result = response.parse
+response.parse
 ```
 
 #### Shipping API (v2)
 
 Provides functionalities for purchasing shipping labels and tracking shipments.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::ShippingV2.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.purchase_shipment(
+api = Peddler.shipping_v2(aws_region, access_token)
+response = api.purchase_shipment(
   body: {
     clientReferenceId: "CLIENT_REF_123",
     shipTo: {
@@ -446,18 +433,16 @@ response = client.purchase_shipment(
     serviceType: "Standard"
   }
 )
-shipment = response.parse
+response.parse
 ```
 
 #### Token API (2021-03-01)
 
 Allows you to create restricted data tokens to access personally identifiable information (PII) in specific API calls.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::Tokens20210301.new("<AWS_REGION>", "<ACCESS_TOKEN>")
-response = client.create_restricted_data_token(
+api = Peddler.tokens_2021_03_01(aws_region, access_token)
+response = api.create_restricted_data_token(
   body: {
     restrictedResources: [
       {
@@ -471,40 +456,43 @@ response = client.create_restricted_data_token(
 restricted_data_token = response.parse["restrictedDataToken"]
 
 # Use the token in subsequent API calls
-orders_client = Peddler::API::Orders20211201.new("<AWS_REGION>", restricted_data_token)
-response = orders_client.get_order(
+orders_api = Peddler.orders_2021_12_01("<AWS_REGION>", restricted_data_token)
+response = orders_api.get_order(
   orderId: "123-1234567-1234567"
 )
-order_details = response.parse
+response.parse
 ```
 
 #### Finances API (v0)
 
 Provides information about financial events for your seller account, such as order payments, refunds, and fees.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::FinancesV0.new
-response = client.list_financial_events(
+api = Peddler.finances_v0(aws_region, access_token)
+response = api.list_financial_events(
   postedAfter: "2023-01-01T00:00:00Z",
   maxResultsPerPage: 100
 )
-financial_events = response.parse["FinancialEvents"]
+response.parse
 ```
 
 #### Sellers API (V1)
 
 Provides information about seller's marketplaces and participation status.
 
-**Example:**
-
 ```ruby
-client = Peddler::API::SellersV1.new
-response = client.get_marketplace_participations
-participations = response.parse["payload"]
+api = Peddler.sellers_v1(aws_region, access_token)
+response = api.get_marketplace_participations
+response.parse
 ```
 
+## TODO
+
+- Code generate models to parse payload. Consider using `dry-struct`.
+- Code generate the APIs section—descriptions and code examples—in this README here.
+- Schedule code generation with GitHub Actions. Push new gem when models change.
+- Review and consider applying [these patches][patches].
+
 [build]: https://github.com/hakanensari/peddler/actions
 [maintainability]: https://codeclimate.com/github/hakanensari/peddler/maintainability
 [test-coverage]: https://codeclimate.com/github/hakanensari/peddler/test_coverage
@@ -513,4 +501,6 @@ participations = response.parse["payload"]
 [register-application]: https://developer-docs.amazon.com/sp-api/docs/registering-your-application
 [view-credentials]: https://developer-docs.amazon.com/sp-api/docs/viewing-your-application-information-and-credentials
 [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/amazon_warehousing_and_distribution_2024_05_09.rb

@@ -3,6 +3,12 @@
 require "peddler/api"
 
 module Peddler
+  class << self
+    def amazon_warehousing_and_distribution_2024_05_09(...)
+      API::AmazonWarehousingAndDistribution20240509.new(...)
+    end
+  end
+
   class API
     # The Selling Partner API for Amazon Warehousing and Distribution
     #
@@ -11,35 +17,39 @@ module Peddler
     class AmazonWarehousingAndDistribution20240509 < API
       # Retrieves an AWD inbound shipment.
       #
-      # @param [String] shipment_id ID for the shipment. A shipment contains the cases being inbounded.
-      # @param [String] sku_quantities If equal to `SHOW`, the response includes the shipment SKU quantity details.
+      # @note This operation can make a static sandbox call.
+      # @param shipment_id [String] ID for the shipment. A shipment contains the cases being inbounded.
+      # @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
-      def get_inbound_shipment(shipment_id, sku_quantities: nil)
+      def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
         path = "/awd/2024-05-09/inboundShipments/#{shipment_id}"
         params = {
           "skuQuantities" => sku_quantities,
         }.compact
 
-        rate_limit(2.0).get(path, params:)
+        meter(rate_limit).get(path, params:)
       end
 
       # Retrieves a summary of all the inbound AWD shipments associated with a merchant, with the ability to apply
       # optional filters.
       #
-      # @param [String] sort_by Field to sort results by. By default, the response will be sorted by UPDATED_AT.
-      # @param [String] sort_order Sort the response in ASCENDING or DESCENDING order. By default, the response will be
+      # @note This operation can make a static sandbox call.
+      # @param sort_by [String] Field to sort results by. By default, the response will be sorted by UPDATED_AT.
+      # @param sort_order [String] Sort the response in ASCENDING or DESCENDING order. By default, the response will be
       #   sorted in DESCENDING order.
-      # @param [String] shipment_status Filter by inbound shipment status.
-      # @param [String] updated_after List the inbound shipments that were updated after a certain time (inclusive). The
-      #   date must be in [ISO 8601](https://developer-docs.amazon.com/sp-api/docs/iso-8601) format.
-      # @param [String] updated_before List the inbound shipments that were updated before a certain time (inclusive).
-      #   The date must be in [ISO 8601](https://developer-docs.amazon.com/sp-api/docs/iso-8601) format.
-      # @param [Integer] max_results Maximum number of results to return.
-      # @param [String] next_token Token to retrieve the next set of paginated results.
+      # @param shipment_status [String] Filter by inbound shipment status.
+      # @param updated_after [String] List the inbound shipments that were updated after a certain time (inclusive). The
+      #   date must be in {https://developer-docs.amazon.com/sp-api/docs/iso-8601 ISO 8601} format.
+      # @param updated_before [String] List the inbound shipments that were updated before a certain time (inclusive).
+      #   The date must be in {https://developer-docs.amazon.com/sp-api/docs/iso-8601 ISO 8601} format.
+      # @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
       def list_inbound_shipments(sort_by: nil, sort_order: nil, shipment_status: nil, updated_after: nil,
-        updated_before: nil, max_results: nil, next_token: nil)
+        updated_before: nil, max_results: 25, next_token: nil, rate_limit: 1.0)
         path = "/awd/2024-05-09/inboundShipments"
         params = {
           "sortBy" => sort_by,
@@ -51,19 +61,21 @@ module Peddler
           "nextToken" => next_token,
         }.compact
 
-        rate_limit(1.0).get(path, params:)
+        meter(rate_limit).get(path, params:)
       end
 
       # Lists AWD inventory associated with a merchant with the ability to apply optional filters.
       #
-      # @param [String] sku Filter by seller or merchant SKU for the item.
-      # @param [String] sort_order Sort the response in `ASCENDING` or `DESCENDING` order.
-      # @param [String] details Set to `SHOW` to return summaries with additional inventory details. Defaults to `HIDE,`
+      # @note This operation can make a static sandbox call.
+      # @param sku [String] Filter by seller or merchant SKU for the item.
+      # @param sort_order [String] Sort the response in `ASCENDING` or `DESCENDING` order.
+      # @param details [String] Set to `SHOW` to return summaries with additional inventory details. Defaults to `HIDE,`
       #   which returns only inventory summary totals.
-      # @param [String] next_token Token to retrieve the next set of paginated results.
-      # @param [Integer] max_results Maximum number of results to return.
+      # @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
-      def list_inventory(sku: nil, sort_order: nil, details: nil, next_token: nil, max_results: nil)
+      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 = {
           "sku" => sku,
@@ -73,7 +85,7 @@ module Peddler
           "maxResults" => max_results,
         }.compact
 
-        rate_limit(2.0).get(path, params:)
+        meter(rate_limit).get(path, params:)
       end
     end
   end