vacuum 4.3.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9defa7d4e94d0039667f94ede365982df2d9fac5a63be691a90e0efe3124aa1
-  data.tar.gz: fc35f8f66b767c8f8a9951e83cd247611b00c221715ca633eb84916d6d9d294c
+  metadata.gz: 0ab3db70bf188be7e645a18cd7faa49836662625763031a72e213af37b246d78
+  data.tar.gz: 1558eea1b389f27c029efba19c9dd244d8c594eb056ed944e0016e4dc362dbd8
 SHA512:
-  metadata.gz: e21de47a9ce2ab5fdfb290c7d429e884c9c41c09e19a276ae76a90b2157aa38f83e99538633f2c7cad26cdc85e595885f28654d6072dd308fd87cd793fb36633
-  data.tar.gz: 619767b577fc2ecdcd04e4f034973a244d9b5f37319094df8fb58633c048c8644bce310fe5b16c0e27bb432ec7b7760b29689598b9417af3c37ca3c698d82685
+  metadata.gz: b677583ab6f8759042ce9e7805f1646e72af0b307e22b55a433c7f141b9ab4e21a17d4969a9741a503c1e5940fe6c4912abc3bf4b693538d8fa31f01874d7c20
+  data.tar.gz: 07fe15c4f43ab1735d0c6cd111cb94f6fb79a1c17ed2f33e1e94ea08e30630d78f52a50193f6945767171aede03d3be6393c3b5b7fa8d2adcf7196569f701e25

data/README.md

@@ -1,14 +1,6 @@
 # Vacuum
 
-[![Build](https://github.com/hakanensari/vacuum/workflows/build/badge.svg)](https://github.com/hakanensari/vacuum/actions)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ffbab4aa5fedf5780332/maintainability)](https://codeclimate.com/github/hakanensari/vacuum/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/ffbab4aa5fedf5780332/test_coverage)](https://codeclimate.com/github/hakanensari/vacuum/test_coverage)
-
-Vacuum is a Ruby wrapper to [Amazon Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/). The API provides programmatic access to query product information on the Amazon marketplaces.
-
-Cart Form functionality is not covered by this gem but is a primary focus on [carriage gem](https://github.com/skatkov/carriage)
-
-You need to [register first](https://webservices.amazon.com/paapi5/documentation/register-for-pa-api.html) to use the API.
+Vacuum is a Ruby wrapper to the [Amazon Creators API](https://affiliate-program.amazon.com/creatorsapi/docs/en-us/). The API provides programmatic access to product information on the Amazon marketplaces.
 
 ![vacuum](https://github.com/hakanensari/vacuum/blob/main/images/vacuum.jpg?raw=true)
 
@@ -16,40 +8,56 @@ You need to [register first](https://webservices.amazon.com/paapi5/documentation
 
 ### Getting Started
 
-Create a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.
+Create a client with your credentials.
 
 ```ruby
-request = Vacuum.new(marketplace: 'US',
-                     access_key: '<ACCESS_KEY>',
-                     secret_key: '<SECRET_KEY>',
-                     partner_tag: '<PARTNER_TAG>')
+client = Vacuum.new(
+  credential_id: "YOUR_CREDENTIAL_ID",
+  credential_secret: "YOUR_CREDENTIAL_SECRET",
+  version: "2.1"
+)
 ```
 
+The client handles authentication automatically and caches access tokens for one hour.
+
 You can now access the API using the available operations.
 
 ```ruby
-response = request.search_items(title: 'lean startup')
-puts response.to_h
+response = client.search_items(
+  marketplace: "www.amazon.com",
+  partner_tag: "yourtag-20",
+  keywords: "lean startup"
+)
+response.parse
 ```
 
-Create a persistent connection to make multiple requests.
+### Versions and Marketplaces
 
-```ruby
-request.persistent
-```
+The `version` determines which authentication endpoint to use. Versions `2.x` use Amazon Cognito; versions `3.x` use Login with Amazon (LwA).
+
+| Version | Region |
+|---------|--------|
+| `"2.1"` | North America |
+| `"2.2"` | Europe |
+| `"2.3"` | Far East |
+| `"3.1"` | North America |
+| `"3.2"` | Europe |
+| `"3.3"` | Far East |
 
 ### Operations
 
-Refer to the [API docs](https://webservices.amazon.com/paapi5/documentation/) for more detailed information.
+Each operation requires `marketplace` (e.g., `"www.amazon.com"`) and `partner_tag` parameters.
 
 #### GetBrowseNodes
 
-Given a BrowseNodeId, the `GetBrowseNodes` operation returns details about the specified browse node, like name, children and ancestors, depending on the resources specified in the request. The names and browse node IDs of the children and ancestor browse nodes are also returned. `GetBrowseNodes` enables you to traverse the browse node hierarchy to find a browse node.
+Given a BrowseNodeId, the `GetBrowseNodes` operation returns details about the specified browse node, like name, children and ancestors, depending on the resources specified in the request.
 
 ```ruby
-request.get_browse_nodes(
-  browse_node_ids: ['283155', '3040'],
-  resources: ['BrowseNodes.Ancestor', 'BrowseNodes.Children']
+client.get_browse_nodes(
+  marketplace: "www.amazon.com",
+  partner_tag: "yourtag-20",
+  browse_node_ids: ["283155", "3040"],
+  resources: ["browseNodes.ancestor", "browseNodes.children"]
 )
 ```
 
@@ -58,23 +66,27 @@ request.get_browse_nodes(
 Given an Item identifier, the `GetItems` operation returns the item attributes, based on the resources specified in the request.
 
 ```ruby
-request.get_items(
-  item_ids: ['B0199980K4', 'B000HZD168', 'B01180YUXS', 'B00BKQTA4A'],
-  resources: ['Images.Primary.Small', 'ItemInfo.Title', 'ItemInfo.Features',
-              'Offers.Summaries.HighestPrice' , 'ParentASIN']
+client.get_items(
+  marketplace: "www.amazon.com",
+  partner_tag: "yourtag-20",
+  item_ids: ["B0199980K4", "B000HZD168"],
+  resources: ["images.primary.small", "itemInfo.title", "itemInfo.features",
+              "offersV2.listings.price", "parentASIN"]
 )
 ```
 
 #### GetVariations
 
-Given an ASIN, the `GetVariations` operation returns a set of items that are the same product, but differ according to a consistent theme, for example size and color. These items which differ according to a consistent theme are called variations. A variation is a child ASIN. The parent ASIN is an abstraction of the children items. For example, a shirt is a parent ASIN and parent ASINs cannot be sold. A child ASIN would be a blue shirt, size 16, sold by MyApparelStore. This child ASIN is one of potentially many variations. The ways in which variations differ are called dimensions.
+Given an ASIN, the `GetVariations` operation returns a set of items that are the same product, but differ according to a consistent theme, for example size and color.
 
 ```ruby
-request.get_variations(
-  asin: 'B00422MCUS',
-  resources: ['ItemInfo.Title', 'VariationSummary.Price.HighestPrice',
-              'VariationSummary.Price.LowestPrice',
-              'VariationSummary.VariationDimension']
+client.get_variations(
+  marketplace: "www.amazon.com",
+  partner_tag: "yourtag-20",
+  asin: "B00422MCUS",
+  resources: ["itemInfo.title", "variationSummary.price.highestPrice",
+              "variationSummary.price.lowestPrice",
+              "variationSummary.variationDimension"]
 )
 ```
 
@@ -83,65 +95,35 @@ request.get_variations(
 The `SearchItems` operation searches for items on Amazon based on a search query. The API returns up to ten items per search request.
 
 ```ruby
-request.search_items(keywords: 'harry potter')
+client.search_items(
+  marketplace: "www.amazon.com",
+  partner_tag: "yourtag-20",
+  keywords: "harry potter"
+)
 ```
 
 ### Response
 
-Consume a response by parsing it into a Ruby hash.
-
-```ruby
-response.to_h
-```
-
-You can also `#dig` into this hash.
-
-```ruby
-response.dig('ItemsResult', 'Items')
-```
-
-### Logging
-
-Write requests and reponses to a logger using the logging feature of the [HTTP gem](https://github.com/httprb/http) under the hood:
-
-```ruby
-require 'logger'
-
-logger = Logger.new(STDOUT)
-request.use(logging: {logger: logger})
-```
-
-### Bring your parser
-You can extend Vacuum with a custom parser. Just swap the original with a class or module that responds to `.parse`.
+Parse the response body into a hash.
 
 ```ruby
-response.parser = MyParser
-response.parse
+response.parse.dig("searchResult", "items")
 ```
 
-If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.
-
-### VCR
+### Shared Token Cache
 
-If you are using [VCR](https://github.com/vcr/vcr) to test an app that accesses the API, you can use the custom VCR matcher of Vacuum to stub requests.
+By default, each client instance caches its own access token. In multi-process environments like Rails, you can share the token across processes by providing a cache store.
 
 ```ruby
-require 'vacuum/matcher'
-
-# in your test
-VCR.insert_cassette('cassette_name',
-                    match_requests_on: [Vacuum::Matcher])
+client = Vacuum.new(
+  credential_id: "YOUR_CREDENTIAL_ID",
+  credential_secret: "YOUR_CREDENTIAL_SECRET",
+  version: "2.1",
+  cache: Rails.cache
+)
 ```
 
-In RSpec, use the `:paapi` metadata.
-
-```ruby
-require 'vacuum/matcher'
-
-# in your test
-it 'queries Amazon', :paapi do
-end
-```
+The cache must respond to `fetch(key, expires_in:, &block)`.
 
 ## Development
 
@@ -151,30 +133,16 @@ Clone the repo and install dependencies.
 bundle install
 ```
 
-Tests and Rubocop should now pass as-is.
+Run tests and Rubocop.
 
 ```sh
 bundle exec rake
 ```
 
-By default, the tests stub requests. Use the `RECORD` env var to record new interactions.
-
-```sh
-RECORD=true bundle exec rake test
-```
-
-You can set the `LIVE` env var to run all tests against live data.
-
-```sh
-LIVE=true bundle exec rake test
-```
-
-In either case, add actual API credentials to a [`locales.yml`](https://github.com/hakanensari/vacuum/blob/master/test/locales.yml.example) file under `test`.
-
-## Getting Help
+To run API tests, copy `spec/credentials.yml.example` to `spec/credentials.yml` and fill in your credentials.
 
-* Ask specific questions about the API on the [Amazon forum](https://forums.aws.amazon.com/forum.jspa?forumID=9).
-* Report bugs in [GitHub issues](https://github.com/hakanensari/vacuum/issues).
-* Discuss potential features in [GitHub Discussions](https://github.com/hakanensari/vacuum/discussions).
+---
 
+> Amazon is a $250 billion dollar company that reacts to you buying a vacuum by going THIS GUY LOVES BUYING VACUUMS HERE ARE SOME MORE VACUUMS
 
+— [@kibblesmith](https://web.archive.org/web/2017/https://twitter.com/kibblesmith/status/724817086309142529)

data/lib/vacuum/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "http"
+
+module Vacuum
+  # A client for the Amazon Creators API
+  #
+  # Handles authentication automatically and caches access tokens.
+  #
+  # @example Basic usage (v2.x)
+  #   client = Vacuum::Client.new(
+  #     credential_id: "YOUR_CREDENTIAL_ID",
+  #     credential_secret: "YOUR_CREDENTIAL_SECRET",
+  #     version: "2.1"
+  #   )
+  #
+  # @example Basic usage (v3.x)
+  #   client = Vacuum::Client.new(
+  #     credential_id: "YOUR_CREDENTIAL_ID",
+  #     credential_secret: "YOUR_CREDENTIAL_SECRET",
+  #     version: "3.3"
+  #   )
+  #
+  # @example With shared cache (for multi-process environments like Rails)
+  #   client = Vacuum::Client.new(
+  #     credential_id: "YOUR_CREDENTIAL_ID",
+  #     credential_secret: "YOUR_CREDENTIAL_SECRET",
+  #     version: "2.1",
+  #     cache: Rails.cache
+  #   )
+  class Client
+    AUTH_URLS = {
+      "2.1" => "https://creatorsapi.auth.us-east-1.amazoncognito.com/oauth2/token",
+      "2.2" => "https://creatorsapi.auth.eu-south-2.amazoncognito.com/oauth2/token",
+      "2.3" => "https://creatorsapi.auth.us-west-2.amazoncognito.com/oauth2/token",
+      "3.1" => "https://api.amazon.com/auth/o2/token",
+      "3.2" => "https://api.amazon.co.uk/auth/o2/token",
+      "3.3" => "https://api.amazon.co.jp/auth/o2/token",
+    }.freeze
+
+    API_URL = "https://creatorsapi.amazon/catalog/v1"
+
+    TOKEN_TTL = 3570 # 59.5 minutes (tokens valid for 1 hour)
+
+    # Creates a new client
+    #
+    # @param credential_id [String] Your Creators API credential ID
+    # @param credential_secret [String] Your Creators API credential secret
+    # @param version [String] API version ("2.1"-"2.3" for Cognito, "3.1"-"3.3" for LwA)
+    # @param cache [#fetch] Optional cache store
+    # @param http [HTTP::Client]
+    def initialize(version:, credential_id:, credential_secret:, cache: nil, http: HTTP)
+      @version = version
+      @auth_url = AUTH_URLS.fetch(version) do
+        raise ArgumentError, "Unknown version: #{version}"
+      end
+      @credential_id = credential_id
+      @credential_secret = credential_secret
+      @cache = cache
+      @http = http
+    end
+
+    # Returns details about specified browse nodes
+    #
+    # @param marketplace [String] The marketplace (e.g., "www.amazon.com")
+    # @param partner_tag [String] Your partner/tracking tag
+    # @param browse_node_ids [Array<String>] The browse node IDs to look up
+    # @return [HTTP::Response]
+    def get_browse_nodes(marketplace:, partner_tag:, browse_node_ids:, **params)
+      params[:browse_node_ids] = Array(browse_node_ids)
+      request("getBrowseNodes", marketplace:, partner_tag:, **params)
+    end
+
+    # Returns the attributes of one or more items
+    #
+    # @param marketplace [String] The marketplace (e.g., "www.amazon.com")
+    # @param partner_tag [String] Your partner/tracking tag
+    # @param item_ids [Array<String>, String] The item IDs (ASINs) to look up
+    # @return [HTTP::Response]
+    def get_items(marketplace:, partner_tag:, item_ids:, **params)
+      params[:item_ids] = Array(item_ids)
+      request("getItems", marketplace:, partner_tag:, **params)
+    end
+
+    # Returns variations of a product
+    #
+    # @param marketplace [String] The marketplace (e.g., "www.amazon.com")
+    # @param partner_tag [String] Your partner/tracking tag
+    # @param asin [String] The ASIN to get variations for
+    # @return [HTTP::Response]
+    def get_variations(marketplace:, partner_tag:, **params)
+      request("getVariations", marketplace:, partner_tag:, **params)
+    end
+
+    # Searches for items on Amazon
+    #
+    # @param marketplace [String] The marketplace (e.g., "www.amazon.com")
+    # @param partner_tag [String] Your partner/tracking tag
+    # @param keywords [String] Search keywords
+    # @return [HTTP::Response]
+    def search_items(marketplace:, partner_tag:, **params)
+      request("searchItems", marketplace:, partner_tag:, **params)
+    end
+
+    private
+
+    def v3?
+      @version.start_with?("3.")
+    end
+
+    def request(operation, marketplace:, partner_tag:, **params)
+      auth_header = if v3?
+        "Bearer #{access_token}"
+      else
+        "Bearer #{access_token}, Version #{@version}"
+      end
+
+      @http
+        .headers(
+          "Authorization" => auth_header,
+          "x-marketplace" => marketplace,
+        )
+        .post("#{API_URL}/#{operation}", json: camelize_keys(marketplace:, partner_tag:, **params))
+    end
+
+    def camelize_keys(**params)
+      params.transform_keys { |key| key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase } }
+    end
+
+    def access_token
+      if @cache
+        @cache.fetch(cache_key, expires_in: TOKEN_TTL) { fetch_token }
+      else
+        @access_token = fetch_token if token_expired?
+        @access_token
+      end
+    end
+
+    def cache_key
+      "vacuum/#{@credential_id}/token"
+    end
+
+    def token_expired?
+      @access_token.nil? || Time.now >= @token_expires_at
+    end
+
+    def fetch_token
+      response = if v3?
+        fetch_token_lwa
+      else
+        fetch_token_cognito
+      end
+
+      data = response.parse
+      @token_expires_at = Time.now + TOKEN_TTL
+      @access_token = data["access_token"]
+    end
+
+    # v2.x: Cognito with Basic Auth and form-encoded body
+    def fetch_token_cognito
+      @http
+        .basic_auth(user: @credential_id, pass: @credential_secret)
+        .post(@auth_url, form: {
+          grant_type: "client_credentials",
+          scope: "creatorsapi/default",
+        })
+    end
+
+    # v3.x: Login with Amazon (LwA) with JSON body
+    def fetch_token_lwa
+      @http
+        .post(@auth_url, json: {
+          grant_type: "client_credentials",
+          client_id: @credential_id,
+          client_secret: @credential_secret,
+          scope: "creatorsapi::default",
+        })
+    end
+  end
+end

data/lib/vacuum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vacuum
-  VERSION = '4.3.0'
+  VERSION = "5.1.0"
 end

data/lib/vacuum.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
-require 'forwardable'
+require "forwardable"
 
-require 'vacuum/request'
-require 'vacuum/version'
+require "vacuum/client"
+require "vacuum/version"
 
-# Ruby wrapper to the Amazon Product Advertising API
+# Ruby wrapper to the Amazon Creators API
 module Vacuum
   class << self
     extend Forwardable
 
     # @!method new
-    #   Delegates to {Request} to create a new request
+    #   Delegates to {Client} to create a new client
     #
-    #   @return [Request]
-    #   @see Request#initialize
-    def_delegator 'Vacuum::Request', :new
+    #   @return [Client]
+    #   @see Client#initialize
+    def_delegator "Vacuum::Client", :new
   end
 end

metadata

@@ -1,50 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: vacuum
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Hakan Ensari
 - Stanislav Katkov
 bindir: bin
 cert_chain: []
-date: 2025-04-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: aws-sigv4
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-description: A wrapper to the Amazon Product Advertising API
+        version: '5.0'
+description: A wrapper to the Amazon Creators API
 email:
 - hakanensari@gmail.com
 - sk@skylup.com
@@ -55,11 +35,7 @@ files:
 - LICENSE
 - README.md
 - lib/vacuum.rb
-- lib/vacuum/locale.rb
-- lib/vacuum/matcher.rb
-- lib/vacuum/operation.rb
-- lib/vacuum/request.rb
-- lib/vacuum/response.rb
+- lib/vacuum/client.rb
 - lib/vacuum/version.rb
 homepage: https://github.com/hakanensari/vacuum
 licenses:
@@ -80,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Amazon Product Advertising in Ruby
+summary: Amazon Creators API in Ruby
 test_files: []

data/lib/vacuum/locale.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Vacuum
-  # The target locale
-  #
-  # @see https://webservices.amazon.com/paapi5/documentation/common-request-parameters.html#host-and-region
-  class Locale
-    # Raised when the provided marketplace does not correspond to an existing
-    # Amazon locale
-    class NotFound < KeyError; end
-
-    HOSTS_AND_REGIONS = {
-      au: ['webservices.amazon.com.au', 'us-west-2'],
-      be: ['webservices.amazon.be', 'eu-west-1'],
-      br: ['webservices.amazon.com.br', 'us-east-1'],
-      ca: ['webservices.amazon.ca', 'us-east-1'],
-      eg: ['webservices.amazon.eg', 'eu-west-1'],
-      fr: ['webservices.amazon.fr', 'eu-west-1'],
-      de: ['webservices.amazon.de', 'eu-west-1'],
-      in: ['webservices.amazon.in', 'eu-west-1'],
-      ie: ['webservices.amazon.ie', 'eu-west-1'],
-      it: ['webservices.amazon.it', 'eu-west-1'],
-      jp: ['webservices.amazon.co.jp', 'us-west-2'],
-      mx: ['webservices.amazon.com.mx', 'us-east-1'],
-      nl: ['webservices.amazon.nl', 'eu-west-1'],
-      pl: ['webservices.amazon.pl', 'eu-west-1'],
-      sg: ['webservices.amazon.sg', 'us-west-2'],
-      sa: ['webservices.amazon.sa', 'eu-west-1'],
-      es: ['webservices.amazon.es', 'eu-west-1'],
-      se: ['webservices.amazon.se', 'eu-west-1'],
-      tr: ['webservices.amazon.com.tr', 'eu-west-1'],
-      ae: ['webservices.amazon.ae', 'eu-west-1'],
-      gb: ['webservices.amazon.co.uk', 'eu-west-1'],
-      us: ['webservices.amazon.com', 'us-east-1']
-    }.freeze
-    private_constant :HOSTS_AND_REGIONS
-
-    # @return [String]
-    attr_reader :host, :region, :access_key, :secret_key, :partner_tag,
-                :partner_type
-
-    # Creates a locale
-    #
-    # @param [Symbol,String] marketplace
-    # @param [String] access_key
-    # @param [String] secret_key
-    # @param [String] partner_tag
-    # @param [String] partner_type
-    # @raise [NotFound] if marketplace is not found
-    def initialize(marketplace, access_key:, secret_key:, partner_tag:,
-                   partner_type: 'Associates')
-      @host, @region = find_host_and_region(marketplace)
-      @access_key = access_key
-      @secret_key = secret_key
-      @partner_tag = partner_tag
-      @partner_type = partner_type
-    end
-
-    private
-
-    def find_host_and_region(marketplace)
-      marketplace = marketplace.to_sym.downcase
-      marketplace = :gb if marketplace == :uk
-
-      HOSTS_AND_REGIONS.fetch(marketplace)
-    rescue KeyError
-      raise NotFound, "marketplace not found: :#{marketplace}"
-    end
-  end
-end

data/lib/vacuum/matcher.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module Vacuum
-  # Custom VCR matcher for stubbing calls to the Product Advertising API
-  #
-  # The matcher is not required by default.
-  #
-  # @example
-  #    require 'vacuum/matcher'
-  #
-  #    # in your test
-  #    VCR.insert_cassette('cassette_name',
-  #                        match_requests_on: [Vacuum::Matcher])
-  #
-  # @see https://relishapp.com/vcr/vcr/v/5-0-0/docs/request-matching/register-and-use-a-custom-matcher
-  class Matcher
-    IGNORED_KEYS = %w[PartnerTag].freeze
-    private_constant :IGNORED_KEYS
-
-    # @!visibility private
-    attr_reader :requests
-
-    # @!visibility private
-    def self.call(*requests)
-      new(*requests).compare
-    end
-
-    # @!visibility private
-    def initialize(*requests)
-      @requests = requests
-    end
-
-    # @!visibility private
-    def compare
-      uris.reduce(:==) && bodies.reduce(:==)
-    end
-
-    private
-
-    def uris
-      requests.map(&:uri)
-    end
-
-    def bodies
-      requests.map do |req|
-        params = JSON.parse(req.body)
-        IGNORED_KEYS.each { |k| params.delete(k) }
-
-        params
-      end
-    end
-  end
-end
-
-# :nocov:
-if defined?(RSpec)
-  RSpec.configure do |config|
-    config.around do |example|
-      if example.metadata[:paapi]
-        metadata = example.metadata[:paapi]
-        metadata = {} if metadata == true
-        example.metadata[:vcr] = metadata.merge(
-          match_requests_on: [Vacuum::Matcher]
-        )
-      end
-
-      example.run
-    end
-  end
-end
-# :nocov:

data/lib/vacuum/operation.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-require 'aws-sigv4'
-require 'http'
-require 'json'
-
-module Vacuum
-  # An Amazon Product Advertising API operation
-  class Operation
-    # @!visibility private
-    attr_reader :locale, :name, :params
-
-    # Creates a new operation
-    #
-    # @param [String] name
-    # @param [Hash] params
-    # @param [Locale] locale
-    def initialize(name, params:, locale:)
-      @name = name
-      @params = params
-      @locale = locale
-    end
-
-    # @return [Hash]
-    def headers
-      signature.headers.merge(
-        'x-amz-target' =>
-          "com.amazon.paapi5.v1.ProductAdvertisingAPIv1.#{name}",
-        'content-encoding' => 'amz-1.0',
-        'content-type' => 'application/json; charset=utf-8'
-      )
-    end
-
-    # @return [String]
-    def body
-      @body ||= build_body
-    end
-
-    # @return [String]
-    def url
-      @url ||= build_url
-    end
-
-    private
-
-    def build_body
-      hsh = { 'PartnerTag' => locale.partner_tag,
-              'PartnerType' => locale.partner_type }
-
-      params.each do |key, val|
-        key = key.to_s.split('_')
-                 .map { |word| word == 'asin' ? 'ASIN' : word.capitalize }.join
-        hsh[key] = val
-      end
-
-      JSON.generate(hsh)
-    end
-
-    def build_url
-      "https://#{locale.host}/paapi5/#{name.downcase}"
-    end
-
-    def signature
-      signer.sign_request(http_method: 'POST', url:, body:)
-    end
-
-    def signer
-      Aws::Sigv4::Signer.new(service: 'ProductAdvertisingAPI',
-                             region: locale.region,
-                             access_key_id: locale.access_key,
-                             secret_access_key: locale.secret_key,
-                             http_method: 'POST', endpoint: locale.host)
-    end
-  end
-end

data/lib/vacuum/request.rb

@@ -1,173 +0,0 @@
-# frozen_string_literal: true
-
-require 'http'
-
-require 'vacuum/locale'
-require 'vacuum/operation'
-require 'vacuum/response'
-
-module Vacuum
-  # A request to the Amazon Product Advertising API
-  class Request
-    # @return [HTTP::Client]
-    attr_reader :client
-
-    # @return [Locale]
-    attr_reader :locale
-
-    # @return [Operation]
-    attr_reader :operation
-
-    # Creates a new request
-    #
-    # @overload initialize(marketplace: :us, access_key:, secret_key:, partner_tag:, partner_type:)
-    #   @param [Symbol,String] marketplace
-    #   @param [String] access_key
-    #   @param [String] secret_key
-    #   @param [String] partner_tag
-    #   @param [String] partner_type
-    #   @raise [Locale::NotFound] if marketplace is not found
-    def initialize(marketplace: :us, **args)
-      @locale = Locale.new(marketplace, **args)
-      @client = HTTP::Client.new
-    end
-
-    # Returns details about specified browse nodes
-    #
-    # @see https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html
-    # @overload get_browse_nodes(browse_node_ids:, languages_of_preference: nil, marketplace: nil, partner_tag: nil, partner_type: nil, resources: nil)
-    #   @param [Array<String,Integer>,String,Integer] browse_node_ids
-    #   @param [Array<String>,nil] languages_of_preference
-    #   @param [String,nil] marketplace
-    #   @param [String,nil] partner_tag
-    #   @param [String,nil] partner_type
-    #   @param [Array<String>,nil] resources
-    # @return [Response]
-    def get_browse_nodes(browse_node_ids:, **params)
-      params.update(browse_node_ids: Array(browse_node_ids))
-      request('GetBrowseNodes', params)
-    end
-
-    # Returns the attributes of one or more items
-    #
-    # @see https://webservices.amazon.com/paapi5/documentation/get-items.html
-    # @overload get_items(condition: nil, currency_of_preference: nil, item_id_type: nil, item_ids:, languages_of_preference: nil, marketplace: nil, merchant: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil)
-    #   @param [String,nil] condition
-    #   @param [String,nil] currency_of_preference
-    #   @param [String,nil] item_id_type
-    #   @param [Array<String>,String] item_ids
-    #   @param [Array<String>,nil] languages_of_preference
-    #   @param [String,nil] marketplace
-    #   @param [String,nil] merchant
-    #   @param [Integer,nil] offer_count
-    #   @param [String,nil] partner_tag
-    #   @param [String,nil] partner_type
-    #   @param [Array<String>,nil] resources
-    # @return [Response]
-    def get_items(item_ids:, **params)
-      params.update(item_ids: Array(item_ids))
-      request('GetItems', params)
-    end
-
-    # Returns a set of items that are the same product, but differ according to
-    # a consistent theme
-    #
-    # @see https://webservices.amazon.com/paapi5/documentation/get-variations.html
-    # @overload get_variations(asin:, condition: nil, currency_of_preference: nil, languages_of_preference: nil, marketplace: nil, merchant: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil, variation_count: nil, variation_page: nil)
-    #   @param [String] asin
-    #   @param [String,nil] condition
-    #   @param [String,nil] currency_of_preference
-    #   @param [Array<String>,nil] languages_of_preference
-    #   @param [String,nil] marketplace
-    #   @param [String,nil] merchant
-    #   @param [Integer,nil] offer_count
-    #   @param [String,nil] partner_tag
-    #   @param [String,nil] partner_type
-    #   @param [Array<String>,nil] resources
-    #   @param [Integer,nil] variation_count
-    #   @param [Integer,nil] variation_page
-    #   @return [Response]
-    def get_variations(**params)
-      request('GetVariations', params)
-    end
-
-    # Searches for items on Amazon based on a search query
-    #
-    # @see https://webservices.amazon.com/paapi5/documentation/search-items.html
-    # @overload search_items(actor: nil, artist: nil, author: nil, availability: nil, brand: nil, browse_node_id: nil, condition: nil, currency_of_preference: nil, delivery_flags: nil, item_count: nil, item_page: nil, keywords: nil, languages_of_preference: nil, marketplace: nil, max_price: nil, merchant: nil, min_price: nil, min_reviews_rating: nil, min_savings_percent: nil, offer_count: nil, partner_tag: nil, partner_type: nil, resources: nil, search_index: nil, sort_by: nil, title: nil)
-    #   @param [String,nil] actor
-    #   @param [String,nil] artist
-    #   @param [String,nil] availability
-    #   @param [String,nil] brand
-    #   @param [Integer,nil] browse_node_id
-    #   @param [String,nil] condition
-    #   @param [String,nil] currency_of_preference
-    #   @param [Array<String>,nil] delivery_flags
-    #   @param [Integer,nil] item_count
-    #   @param [Integer,nil] item_page
-    #   @param [String,nil] keywords
-    #   @param [Array<String>,nil] languages_of_preference
-    #   @param [Integer,nil] max_price
-    #   @param [String,nil] merchant
-    #   @param [Integer,nil] min_price
-    #   @param [Integer,nil] min_reviews_rating
-    #   @param [Integer,nil] min_savings_percent
-    #   @param [Integer,nil] offer_count
-    #   @param [Hash,nil] properties
-    #   @param [Array<String>,nil] resources
-    #   @param [String,nil] search_index
-    #   @param [String,nil] sort_by
-    #   @param [String,nil] title
-    # @return [Response]
-    def search_items(**params)
-      request('SearchItems', params)
-    end
-
-    # Flags as persistent
-    #
-    # @param [Integer] timeout
-    # @return [self]
-    def persistent(timeout: 5)
-      host = "https://#{locale.host}"
-      @client = client.persistent(host, timeout:)
-
-      self
-    end
-
-    # @!method use(*features)
-    #   Turn on {https://github.com/httprb/http HTTP} features
-    #
-    #   @param features
-    #   @return [self]
-    #
-    # @!method via(*proxy)
-    #   Make a request through an HTTP proxy
-    #
-    #   @param [Array] proxy
-    #   @raise [HTTP::Request::Error] if HTTP proxy is invalid
-    #   @return [self]
-    %i[timeout via through headers use].each do |method_name|
-      define_method(method_name) do |*args, &block|
-        @client = client.send(method_name, *args, &block)
-      end
-    end
-
-    private
-
-    def validate_keywords(params)
-      return unless params[:keywords]
-      return if params[:keywords].is_a?(String)
-
-      raise ArgumentError, ':keyword argument expects a String'
-    end
-
-    def request(operation_name, params)
-      validate_keywords(params)
-      @operation = Operation.new(operation_name, params:, locale:)
-      response = client.headers(operation.headers)
-                       .post(operation.url, body: operation.body)
-
-      Response.new(response)
-    end
-  end
-end

data/lib/vacuum/response.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require 'delegate'
-require 'forwardable'
-require 'json'
-
-module Vacuum
-  # A wrapper around the API response
-  class Response < SimpleDelegator
-    extend Forwardable
-
-    # @!method dig(*key)
-    #   Delegates to the Hash returned by {Response#to_h} to extract a nested
-    #   value specified by the sequence of keys
-    #
-    #   @param [String] key one or more keys
-    #   @see https://ruby-doc.org/core/Hash.html#method-i-dig
-    def_delegator :to_h, :dig
-
-    class << self
-      # @return [nil,.parse] an optional custom parser
-      attr_accessor :parser
-    end
-
-    # @return [nil,.parse] an optional custom parser
-    attr_writer :parser
-
-    # @!attribute [r] parser
-    # @return [nil,.parse] an optional custom parser
-    def parser
-      @parser || self.class.parser
-    end
-
-    # Parses the response body
-    #
-    # @note Delegates to {#to_h} if no custom parser is set
-    def parse
-      parser&.parse(body) || to_h
-    end
-
-    # Casts body to Hash
-    #
-    # @return [Hash]
-    def to_h
-      JSON.parse(body)
-    end
-  end
-end