Add support for static sandboxes

bin/generate-code

@@ -99,17 +99,19 @@ module Generator
         code = operation["responses"].keys.find { |code| code.start_with?("2") }
         static_sandbox = operation["responses"][code]&.delete("x-amzn-api-sandbox")&.fetch("static")
 
+        rate_limit = extract_rate_limit(operation["description"])
+
         operation_parameters = (shared_parameters + (operation["parameters"] || [])).uniq { |p| p["name"] }
         parameters = operation_parameters.select { |p| p["name"] }
         parameters << {
           "name" => "rate_limit",
           "type" => "Float",
           "required" => false,
           "description" => "Requests per second",
-          "default" => (rate_limit = extract_rate_limit(operation)),
+          "default" => rate_limit,
         }
-
         operation.merge(
+          "description" => clean_description(operation["description"]),
           "path" => path,
           "method" => method.upcase,
           "rate_limit" => rate_limit,
@@ -225,20 +227,15 @@ module Generator
     lines.join("\n").strip
   end
 
-  def generate_method_docs(description, parameters)
-    cleaned_description = clean_description(description)
-    formatted_description = format_text(cleaned_description, 6)
+  def generate_method_docs(operation)
+    formatted_description = format_text(operation["description"], 6)
 
-    if parameters.empty?
-      formatted_description
-    else
-      param_docs = generate_parameter_docs(parameters)
-      "#{formatted_description}\n#\n#{param_docs}"
-    end
+    param_docs = generate_parameter_docs(operation)
+    "#{formatted_description}\n#\n#{param_docs}"
   end
 
-  def generate_parameter_docs(parameters)
-    parameters.map do |param|
+  def generate_parameter_docs(operation)
+    output = operation["parameters"].map do |param|
       param_type = param["type"] ? param["type"].capitalize : "Object"
       param_type = "Hash" if param["schema"]
       if param_type == "Array"
@@ -250,11 +247,21 @@ module Generator
         param_description = convert_links_to_markdown(param_description)
       end
       format_text("@param [#{param_type}] #{snakecase(param["name"])} #{param_description}", 6)
-    end.join("\n")
+    end
+
+    if operation["sandbox_only"]
+      output.unshift(format_text("@note This operation is sandbox-only.", 6))
+    end
+    if operation["static_sandbox"]
+      output.unshift(format_text("@note This operation can make a static sandbox call.", 6))
+    elsif operation["dynamic_sandbox"]
+      output.unshift(format_text("@note This operation can make a dynamic sandbox call.", 6))
+    end
+
+    output.join("\n")
   end
 
-  def extract_rate_limit(operation)
-    description = operation["description"]
+  def extract_rate_limit(description)
     return unless description
 
     # Match rate limit from tables with or without "Plan type" column

bin/templates/api.rb.erb

@@ -7,10 +7,10 @@ class API
 <%= format_text(model["info"]["description"], 4) %>
 class <%= api_data[:class_name] %> < API
   <% operations.each do |operation| %>
-    <%= generate_method_docs(operation["description"], operation["parameters"]) %>
+    <%= generate_method_docs(operation) %>
     # @return [Hash] The API response
     def <%= snakecase(operation["operationId"]) %><%= generate_parameters(operation["parameters"], snakecase(operation["operationId"]), 6) %>
-    <% unless operation["dynamic_sandbox"] -%>
+    <% if !operation["static_sandbox"] && !operation["dynamic_sandbox"] -%>
         cannot_sandbox!
       <% end %>
       path = "<%= operation["path"] %>"

lib/peddler/api/amazon_warehousing_and_distribution_2024_05_09.rb

@@ -11,14 +11,13 @@ class API
     class AmazonWarehousingAndDistribution20240509 < API
       # Retrieves an AWD inbound shipment.
       #
+      # @note This operation can make a static sandbox call.
       # @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.
       #   Defaults to `HIDE`, in which case the response does not contain SKU quantities
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
-        cannot_sandbox!
-
         path = "/awd/2024-05-09/inboundShipments/#{shipment_id}"
         params = {
           "skuQuantities" => sku_quantities,
@@ -30,6 +29,7 @@ def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
       # Retrieves a summary of all the inbound AWD shipments associated with a merchant, with the ability to apply
       # optional filters.
       #
+      # @note This operation can make a static sandbox call.
       # @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
       #   sorted in DESCENDING order.
@@ -44,7 +44,6 @@ def get_inbound_shipment(shipment_id, sku_quantities: nil, rate_limit: 2.0)
       # @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: 25, next_token: nil, rate_limit: 1.0)
-        cannot_sandbox!
 
         path = "/awd/2024-05-09/inboundShipments"
         params = {
@@ -62,6 +61,7 @@ def list_inbound_shipments(sort_by: nil, sort_order: nil, shipment_status: nil,
 
       # Lists AWD inventory associated with a merchant with the ability to apply optional filters.
       #
+      # @note This operation can make a static sandbox call.
       # @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,`
@@ -71,8 +71,6 @@ def list_inbound_shipments(sort_by: nil, sort_order: nil, shipment_status: nil,
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def list_inventory(sku: nil, sort_order: nil, details: nil, next_token: nil, max_results: 25, rate_limit: 2.0)
-        cannot_sandbox!
-
         path = "/awd/2024-05-09/inventory"
         params = {
           "sku" => sku,

lib/peddler/api/catalog_items_2020_12_01.rb

@@ -12,6 +12,7 @@ class API
     class CatalogItems20201201 < API
       # Search for and return a list of Amazon catalog items and associated information.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Array<String>] keywords A comma-delimited list of words or item identifiers to search the Amazon catalog
       #   for.
       # @param [Array<String>] marketplace_ids A comma-delimited list of Amazon marketplace identifiers for the request.
@@ -30,7 +31,6 @@ class CatalogItems20201201 < API
       # @return [Hash] The API response
       def search_catalog_items(keywords, marketplace_ids, included_data: "summaries", brand_names: nil,
         classification_ids: nil, page_size: 10, page_token: nil, keywords_locale: nil, locale: nil, rate_limit: 2.0)
-        cannot_sandbox!
 
         path = "/catalog/2020-12-01/items"
         params = {
@@ -50,6 +50,7 @@ def search_catalog_items(keywords, marketplace_ids, included_data: "summaries",
 
       # Retrieves details for an item in the Amazon catalog.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] asin The Amazon Standard Identification Number (ASIN) of the item.
       # @param [Array<String>] marketplace_ids A comma-delimited list of Amazon marketplace identifiers. Data sets in
       #   the response contain data only for the specified marketplaces.
@@ -60,8 +61,6 @@ def search_catalog_items(keywords, marketplace_ids, included_data: "summaries",
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_catalog_item(asin, marketplace_ids, included_data: "summaries", locale: nil, rate_limit: 2.0)
-        cannot_sandbox!
-
         path = "/catalog/2020-12-01/items/#{asin}"
         params = {
           "marketplaceIds" => marketplace_ids,

lib/peddler/api/catalog_items_2022_04_01.rb

@@ -13,6 +13,7 @@ class CatalogItems20220401 < API
       # Search for and return a list of Amazon catalog items and associated information either by identifier or by
       # keywords.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Array<String>] identifiers A comma-delimited list of product identifiers to search the Amazon catalog
       #   for. **Note:** Cannot be used with `keywords`.
       # @param [String] identifiers_type Type of product identifiers to search the Amazon catalog for. **Note:**
@@ -41,7 +42,6 @@ def search_catalog_items(
         seller_id: nil, keywords: nil, brand_names: nil, classification_ids: nil, page_size: 10, page_token: nil,
         keywords_locale: nil, rate_limit: 2.0
       )
-        cannot_sandbox!
 
         path = "/catalog/2022-04-01/items"
         params = {
@@ -64,6 +64,7 @@ def search_catalog_items(
 
       # Retrieves details for an item in the Amazon catalog.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] asin The Amazon Standard Identification Number (ASIN) of the item.
       # @param [Array<String>] marketplace_ids A comma-delimited list of Amazon marketplace identifiers. Data sets in
       #   the response contain data only for the specified marketplaces.
@@ -74,8 +75,6 @@ def search_catalog_items(
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_catalog_item(asin, marketplace_ids, included_data: ["summaries"], locale: nil, rate_limit: 2.0)
-        cannot_sandbox!
-
         path = "/catalog/2022-04-01/items/#{asin}"
         params = {
           "marketplaceIds" => marketplace_ids,

lib/peddler/api/catalog_items_v0.rb

@@ -16,6 +16,7 @@ class CatalogItemsV0 < API
       # to avoid service disruption. _Note:_ The [`listCatalogCategories`](#get-catalogv0categories) operation is not
       # being deprecated and you can continue to make calls to it.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] marketplace_id A marketplace identifier. Specifies the marketplace for which items are returned.
       # @param [String] query Keyword(s) to use to search for items in the catalog. Example: 'harry potter books'.
       # @param [String] query_context_id An identifier for the context within which the given search will be performed.
@@ -35,7 +36,6 @@ class CatalogItemsV0 < API
       # @return [Hash] The API response
       def list_catalog_items(marketplace_id, query: nil, query_context_id: nil, seller_sku: nil, upc: nil, ean: nil,
         isbn: nil, jan: nil, rate_limit: nil)
-        cannot_sandbox!
 
         path = "/catalog/v0/items"
         params = {
@@ -59,13 +59,12 @@ def list_catalog_items(marketplace_id, query: nil, query_context_id: nil, seller
       # [`listCatalogCategories`](#get-catalogv0categories) operation is not being deprecated and you can continue to
       # make calls to it.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] marketplace_id A marketplace identifier. Specifies the marketplace for the item.
       # @param [String] asin The Amazon Standard Identification Number (ASIN) of the item.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_catalog_item(marketplace_id, asin, rate_limit: nil)
-        cannot_sandbox!
-
         path = "/catalog/v0/items/#{asin}"
         params = {
           "MarketplaceId" => marketplace_id,
@@ -76,15 +75,14 @@ def get_catalog_item(marketplace_id, asin, rate_limit: nil)
 
       # Returns the parent categories to which an item belongs, based on the specified ASIN or SellerSKU.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] marketplace_id A marketplace identifier. Specifies the marketplace for the item.
       # @param [String] asin The Amazon Standard Identification Number (ASIN) of the item.
       # @param [String] seller_sku Used to identify items in the given marketplace. SellerSKU is qualified by the
       #   seller's SellerId, which is included with every operation that you submit.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def list_catalog_categories(marketplace_id, asin: nil, seller_sku: nil, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/catalog/v0/categories"
         params = {
           "MarketplaceId" => marketplace_id,

lib/peddler/api/data_kiosk_2023_11_15.rb

@@ -12,6 +12,7 @@ class DataKiosk20231115 < API
       # Returns details for the Data Kiosk queries that match the specified filters. See the `createQuery` operation for
       # details about query retention.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Array<String>] processing_statuses A list of processing statuses used to filter queries.
       # @param [Integer] page_size The maximum number of queries to return in a single call.
       # @param [String] created_since The earliest query creation date and time for queries to include in the response,
@@ -27,7 +28,6 @@ class DataKiosk20231115 < API
       # @return [Hash] The API response
       def get_queries(processing_statuses: nil, page_size: 10, created_since: nil, created_until: nil,
         pagination_token: nil, rate_limit: 0.0222)
-        cannot_sandbox!
 
         path = "/dataKiosk/2023-11-15/queries"
         params = {
@@ -47,12 +47,11 @@ def get_queries(processing_statuses: nil, page_size: 10, created_since: nil, cre
       #   a query contains multiple fields with different retentions, the shortest (minimum) retention is applied. The
       #   retention of a query's resulting documents always matches the retention of the query.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Hash] body The body of the request.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def create_query(body, rate_limit: 0.0167)
-        cannot_sandbox!
-
         path = "/dataKiosk/2023-11-15/queries"
 
         meter(rate_limit).post(path, body:)
@@ -63,13 +62,12 @@ def create_query(body, rate_limit: 0.0167)
       # `CANCELLED` will no-op. Cancelled queries are returned in subsequent calls to the `getQuery` and `getQueries`
       # operations.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] query_id The identifier for the query. This identifier is unique only in combination with a
       #   selling partner account ID.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def cancel_query(query_id, rate_limit: 0.0222)
-        cannot_sandbox!
-
         path = "/dataKiosk/2023-11-15/queries/#{query_id}"
 
         meter(rate_limit).delete(path)
@@ -78,12 +76,11 @@ def cancel_query(query_id, rate_limit: 0.0222)
       # Returns query details for the query specified by the `queryId` parameter. See the `createQuery` operation for
       # details about query retention.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] query_id The query identifier.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_query(query_id, rate_limit: 2.0)
-        cannot_sandbox!
-
         path = "/dataKiosk/2023-11-15/queries/#{query_id}"
 
         meter(rate_limit).get(path)
@@ -92,12 +89,11 @@ def get_query(query_id, rate_limit: 2.0)
       # Returns the information required for retrieving a Data Kiosk document's contents. See the `createQuery`
       # operation for details about document retention.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] document_id The identifier for the Data Kiosk document.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_document(document_id, rate_limit: 0.0167)
-        cannot_sandbox!
-
         path = "/dataKiosk/2023-11-15/documents/#{document_id}"
 
         meter(rate_limit).get(path)

lib/peddler/api/easy_ship_2022_03_23.rb

@@ -19,12 +19,11 @@ class EasyShip20220323 < API
       # slots that have either pickup or drop-off handover methods - see **Supported Handover Methods** in the
       # [Marketplace Support Table](doc:easyship-api-v2022-03-23-use-case-guide#marketplace-support-table).
       #
+      # @note This operation can make a static sandbox call.
       # @param [Hash] list_handover_slots_request The request schema for the `listHandoverSlots` operation.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def list_handover_slots(list_handover_slots_request: nil, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/easyShip/2022-03-23/timeSlot"
         body = list_handover_slots_request
 
@@ -34,14 +33,13 @@ def list_handover_slots(list_handover_slots_request: nil, rate_limit: 1.0)
       # Returns information about a package, including dimensions, weight, time slot information for handover, invoice
       # and item information, and status.
       #
+      # @note This operation can make a static sandbox call.
       # @param [String] amazon_order_id An Amazon-defined order identifier. Identifies the order that the seller wants
       #   to deliver using Amazon Easy Ship.
       # @param [String] marketplace_id An identifier for the marketplace in which the seller is selling.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def get_scheduled_package(amazon_order_id, marketplace_id, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/easyShip/2022-03-23/package"
         params = {
           "amazonOrderId" => amazon_order_id,
@@ -62,12 +60,11 @@ def get_scheduled_package(amazon_order_id, marketplace_id, rate_limit: 1.0)
       # Table](doc:easyship-api-v2022-03-23-use-case-guide#marketplace-support-table) to see which documents are
       # supported in each marketplace.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Hash] create_scheduled_package_request The request schema for the `createScheduledPackage` operation.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def create_scheduled_package(create_scheduled_package_request, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/easyShip/2022-03-23/package"
         body = create_scheduled_package_request
 
@@ -80,12 +77,11 @@ def create_scheduled_package(create_scheduled_package_request, rate_limit: 1.0)
       # Table](doc:easyship-api-v2022-03-23-use-case-guide#marketplace-support-table) to see which marketplaces this
       # operation is supported in.
       #
+      # @note This operation can make a static sandbox call.
       # @param [Hash] update_scheduled_packages_request The request schema for the `updateScheduledPackages` operation.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def update_scheduled_packages(update_scheduled_packages_request: nil, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/easyShip/2022-03-23/package"
         body = update_scheduled_packages_request
 
@@ -106,13 +102,12 @@ def update_scheduled_packages(update_scheduled_packages_request: nil, rate_limit
       # we couldn't process. Each entry is composed of an error message describing the reason of the failure, so that
       # sellers can take action. The table below displays the supported request and burst maximum rates:
       #
+      # @note This operation can make a static sandbox call.
       # @param [Hash] create_scheduled_packages_request The request schema for the `createScheduledPackageBulk`
       #   operation.
       # @param [Float] rate_limit Requests per second
       # @return [Hash] The API response
       def create_scheduled_package_bulk(create_scheduled_packages_request, rate_limit: 1.0)
-        cannot_sandbox!
-
         path = "/easyShip/2022-03-23/packages/bulk"
         body = create_scheduled_packages_request