peddler 3.0.0.beta1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f132e3d74dc1f70f5f0d84f84cc75e6d4e9184bd2ed4162e2e805a766341afed
-  data.tar.gz: 65c57dc08f0d1e1b23f87969ec2657d7592ea4590c65d3c18b7e9c9ac612ed71
+  metadata.gz: 989f5bec7dce426405b687e65c4677fe8b359b355d815df799a048ef1907809f
+  data.tar.gz: eec2f1236bf285bf00c7d32e1482ae2fadaadeb2db9f0bc0a9beb64cf3ec7072
 SHA512:
-  metadata.gz: cc5e82f24bd72cebd6d226e713d22e792944e043489da3a7f79245fd5242f1430cef84201643e9ebd5a25d9b5a10c9bbf5ae88e70f27a4d52a7b077482f9760a
-  data.tar.gz: 80a16515b74499a28513058b41eab6a912bcb21249d7748cedd74db9efd7e3ccc2316e896f78b9406c2e1f7d078b667ad73a62a980054cd0982135a9b219fd0f
+  metadata.gz: 361ce5ea21116bbc09efb9590d080db5275f35dbc6717ccd318c291eb32e4b122b24d06ad4f78c9c693298d8e6e70fc81f3d7a128b843b7949579a601683bf91
+  data.tar.gz: 956ad0c6b2b7d1a490dffbf846a4c4415e1323510ac52c0eebdb2b42835f5a2f14354f2e0d16fa19099d0823ed47f09218255e98973735e7ccfa1579f08ccefa

data/README.md

@@ -4,9 +4,16 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/281e6176048f3c0a1ed3/maintainability)][maintainability]
 [![Test Coverage](https://api.codeclimate.com/v1/badges/281e6176048f3c0a1ed3/test_coverage)][test-coverage]
 
+> **_NOTE:_** This README explains the main branch, which may contain unreleased code. For the README of the latest release, please refer to [this link][latest-release-readme].
+
 **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.
+Peddler is automatically generated from the 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.
+
+- [API models][api-models]
+- [API samples][api-samples]
 
 ![Peddler](https://github.com/hakanensari/peddler/blob/main/images/peddler.jpg?raw=true)
 
@@ -15,7 +22,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", "3.0.0.beta1"
+gem "peddler", "~> 3.0"
 ```
 
 And then execute:
@@ -39,53 +46,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,42 +114,37 @@ 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"
 )
-items = response.parse.dig("items")
+items = response.dig("items")
 ```
 
 #### Orders API (v0)
 
 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.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 +152,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, "text/xml; charset=UTF-8")
 
 # 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 +197,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 +218,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 +229,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 +254,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 +280,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 +331,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 +345,34 @@ 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 +393,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 +438,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,46 +461,54 @@ 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
+[latest-release-readme]: https://github.com/lineofflight/peddler/tree/v3.0.0
 [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
 [register-application]: https://developer-docs.amazon.com/sp-api/docs/registering-your-application
+[api-models]: https://github.com/amzn/selling-partner-api-models
+[api-samples]: https://github.com/amzn/selling-partner-api-samples
 [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.rb

@@ -2,14 +2,25 @@
 
 require "http"
 
+require "peddler/endpoint"
 require "peddler/error"
-require "peddler/region"
+require "peddler/marketplace"
+require "peddler/response"
+require "peddler/version"
 
 module Peddler
   # Wraps an Amazon Selling Partner API (SP-API)
   class API
-    # @return [Peddler::Region]
-    attr_reader :region
+    class CannotSandbox < StandardError; end
+    class MustSandbox < StandardError; end
+
+    class << self
+      # @return [#call]
+      attr_accessor :parser
+    end
+
+    # @return [Peddler::Endpoint]
+    attr_reader :endpoint
 
     # @return [String]
     attr_reader :access_token
@@ -17,41 +28,52 @@ module Peddler
     # @param [String] aws_region
     # @param [String] access_token
     def initialize(aws_region, access_token)
-      @region = Region.new(aws_region)
+      @endpoint = Endpoint.find(aws_region)
       @access_token = access_token
+      @sandbox = false
     end
 
-    def endpoint
-      @endpoint ||= region.endpoint
+    # @return [URI::HTTPS]
+    def endpoint_uri
+      sandbox? ? endpoint.sandbox : endpoint.production
     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
     # @return [self]
     def sandbox
-      @endpoint = endpoint.sub(/(?:sandbox.)?sellingpartnerapi/, "sandbox.sellingpartnerapi")
+      @sandbox = true
       self
     end
 
+    # @return [Boolean]
+    def sandbox?
+      @sandbox
+    end
+
     # @see https://developer-docs.amazon.com/sp-api/docs/include-a-user-agent-header-in-all-requests
     # @see https://developer-docs.amazon.com/amazon-shipping/docs/connecting-to-the-selling-partner-api#step-3-add-headers-to-the-uri
     # @return [HTTP::Client]
     def http
       @http ||= HTTP.headers(
-        "Host" => endpoint_host,
+        "Host" => endpoint_uri.host,
         "User-Agent" => user_agent,
         "X-Amz-Access-Token" => access_token,
         "X-Amz-Date" => timestamp,
       )
     end
 
-    # Retries with a rate limit when the API returns a 429
+    # Throttles with a rate limit and retries when the API returns a 429
     #
-    # @param [Float] delay The delay in seconds before retrying
+    # @param [Float] rate_limit The delay in seconds before retrying
     # @return [self]
-    def rate_limit(rate)
-      # HTTP v6.0 will implement retriable
+    def meter(rate_limit)
+      # 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
-      retriable(delay: 1.0 / rate, retry_statuses: [429]) if @http.respond_to?(:retriable)
+      delay = sandbox? ? 0.2 : 1.0 / rate_limit
+      retriable(delay: delay, retry_statuses: [429])
+
       self
     end
 
@@ -75,7 +97,7 @@ module Peddler
     #   @return [self]
     [:via, :use, :retriable].each do |method|
       define_method(method) do |*args, &block|
-        @http = http.send(method, *args, &block)
+        @http = http.send(method, *args, &block) if http.respond_to?(method)
         self
       end
     end
@@ -87,21 +109,37 @@ module Peddler
           options[:json] = options.delete(:body)
         end
 
-        response = http.send(method, [endpoint, path].join, **options)
+        uri = endpoint_uri.tap do |uri|
+          uri.path = path
+        end
+
+        response = http.send(method, uri, **options)
 
         if response.status.client_error?
           error = Error.build(response)
           raise error if error
         end
 
-        response
+        Response.decorate(response, parser:)
       end
     end
 
+    attr_writer :parser
+
+    # @!attribute parser
+    # @return [#call]
+    def parser
+      @parser || self.class.parser
+    end
+
     private
 
-    def endpoint_host
-      URI.parse(endpoint).host
+    def cannot_sandbox!
+      raise CannotSandbox, "cannot run in a sandbox" if sandbox?
+    end
+
+    def must_sandbox!
+      raise MustSandbox, "must run in a sandbox" unless sandbox?
     end
 
     def user_agent