vacuum 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f97f47ef585594e52efc75ac3824e47992ad0ac6cbd688f05363579c9feff3
-  data.tar.gz: 4d0399b9b897cd955cb3c2739a3b2fcb4e393c6ee092270d21d28dab8ee503fc
+  metadata.gz: 93d495272c66aa409a35266354596c893f93dc94f909290143909a3ed3552f8a
+  data.tar.gz: '0812a94c0f3254302468caa19b852e31f7e7e4650166721ed45d49f071db5303'
 SHA512:
-  metadata.gz: eac6cca761cd2ccc75e7eb9d626398505c06400116efe5bb765e5112debb0f3b22da3dab840aa1bbde19de752d841bd836029c6c1bb7f3b12738d74bfecd0e3b
-  data.tar.gz: 8571a8e9c4b64b71038bf7713364c8b56bca14bb08abae6743aaf2cea0a976fe1b0025432ad659b300d8d5763deb05bd9ff4200bdfcb80e52de9a2f3d3e8952c
+  metadata.gz: 473700d6b71e5c6c3228f64fa2e6b78c4efc7d191211a686fb14ec8426f59fa68a6c626c742e1282cd08db8df9e6a0e6ce30b3f43b991908d96fe179cc8c37fd
+  data.tar.gz: 43f66d7d7a0dc877a9e197006d5aa869e14b699f86554181e79794ec2bbe92846e9a2f73b320228f5c552eb8d9e278736284d947a08995e358162f444e299dbc

data/README.md

@@ -1,20 +1,18 @@
 # Vacuum
 
-[![CircleCI](https://circleci.com/gh/hakanensari/vacuum/tree/master.svg?style=svg)](https://circleci.com/gh/hakanensari/vacuum/tree/master)
+[![Build](https://github.com/hakanensari/vacuum/workflows/build/badge.svg)](https://github.com/hakanensari/vacuum/actions)
 
-Vacuum is a light-weight Ruby wrapper to [Amazon Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/). The API provides programmatic access to search and get detailed product information on the Amazon marketplaces.
+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.
+
+You need to [register first](https://webservices.amazon.com/paapi5/documentation/register-for-pa-api.html) to use the API.
 
 ![vacuum](http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png)
 
 ## Usage
 
-Vacuum follows the nomenclature of the Product Advertising API. The examples below are based on examples in the [Amazon docs](https://webservices.amazon.com/paapi5/documentation/).
-
 ### Getting Started
 
-You need to [register as an affiliate](https://affiliate-program.amazon.com) and [apply for API access](https://affiliate-program.amazon.com/assoc_credentials/home) on each marketplace you want to query product information.
-
-Create a request with your marketplace credentials, passing the two-letter country code of the marketplace.
+Create a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.
 
 ```ruby
 request = Vacuum.new(marketplace: 'US',
@@ -23,17 +21,26 @@ request = Vacuum.new(marketplace: 'US',
                      partner_tag: '<PARTNER_TAG>')
 ```
 
-Vacuum uses [HTTPI](https://github.com/savonrb/httpi) under the hood. You can swap the HTTP library it uses if you prefer an alternative one for speed or introspection.
+You can now access the API using the available operations.
+
+```ruby
+response = request.search_items(title: 'lean startup')
+puts response.to_h
+```
+
+Create a persistent connection to make multiple requests.
 
 ```ruby
-HTTPI.adapter = :http
+request.persistent
 ```
 
 ### Operations
 
+Refer to the [API docs](https://webservices.amazon.com/paapi5/documentation/) for more detailed information.
+
 #### 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. 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.
 
 ```ruby
 request.get_browse_nodes(
@@ -69,7 +76,7 @@ request.get_variations(
 
 #### SearchItems
 
-The `SearchItems` operation searches for items on Amazon based on a search query. The Amazon Product Advertising API returns up to ten items per search request.
+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')
@@ -77,46 +84,73 @@ request.search_items(keywords: 'harry potter')
 
 ### Response
 
-The quick and dirty way to consume a response is to parse into a Ruby hash:
+Consume a response by parsing it into a Ruby hash.
 
 ```ruby
 response.to_h
 ```
 
-You can also `#dig` into the returned Hash:
+You can also `#dig` into this hash.
 
 ```ruby
 response.dig('ItemsResult', 'Items')
 ```
 
-You can extend Vacuum with a custom parser. Just swap the original with a class or module that responds to `.parse`.
+### Troubleshooting
+
+In addition to the response payload, the following attributes help you introspect a request.
 
 ```ruby
-response.parser = MyParser
-response.parse
+request.body
+request.headers
+request.url
 ```
 
-If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.
+### VCR
 
-### VCR Support
+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.
+
+```ruby
+require 'vacuum/matcher'
+
+# in your test
+VCR.insert_cassette('cassette_name',
+                    match_requests_on: [Vacuum::Matcher])
+```
 
-If you are using [VCR](https://github.com/vcr/vcr) to test an app that accesses the Product Advertising API, you can use the custom VCR matcher of Vacuum to stub requests.
+In RSpec, consider using custom metadata.
 
 ```ruby
 require 'vacuum/matcher'
 
-VCR.insert_cassette('paapi', match_requests_on: [Vacuum::Matcher])
+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
+
+# in your test
+it 'queries Amazon', :paapi do
+end
 ```
 
-## Testing
+## Development
 
-Tests should pass as-is once you install dependencies.
+Clone the repo and install dependencies. Tests should pass as-is.
 
 ```sh
 bundle exec rake
 ```
 
-By default, all requests are stubbed. Use the `RECORD` env var to record new or modified interactions.
+By default, all requests are stubbed. Use the `RECORD` env var to record new interactions.
 
 ```sh
 bundle exec RECORD=true rake
@@ -128,7 +162,7 @@ You can also run tests against live data.
 bundle exec LIVE=true rake
 ```
 
-In either case, you will want to add actual API credentials to a [`locales.yml`](https://github.com/hakanensari/vacuum/blob/master/test/locales.yml.example) file in the `test` directory.
+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
 

data/lib/vacuum.rb

@@ -10,6 +10,11 @@ module Vacuum
   class << self
     extend Forwardable
 
+    # @!method new
+    #   Delegates to {Request} to create a new request
+    #
+    #   @return [Request]
+    #   @see Request#initialize
     def_delegator 'Vacuum::Request', :new
   end
 end

data/lib/vacuum/locale.rb

@@ -1,53 +1,62 @@
 # frozen_string_literal: true
 
 module Vacuum
-  # The target Amazon locale
-  # @api private
+  # The target locale
+  #
+  # @see https://webservices.amazon.com/paapi5/documentation/common-request-parameters.html#host-and-region
   class Locale
-    class NotFound < ArgumentError; end
-
-    attr_reader :code, :domain, :region
-
-    def self.find(code)
-      code = code.to_sym.downcase
-      code = :gb if code == :uk
-
-      @all.find { |locale| locale.code == code } || raise(NotFound)
-    end
-
-    def initialize(code, domain, region)
-      @code = code
-      @domain = domain
-      @region = region
+    # Raised when the provided marketplace does not correspond to an existing
+    # Amazon locale
+    class NotFound < KeyError; end
+
+    # @!visibility private
+    HOSTS_AND_REGIONS = {
+      au: ['webservices.amazon.com.au', 'us-west-2'],
+      br: ['webservices.amazon.com.br', 'us-east-1'],
+      ca: ['webservices.amazon.ca', 'us-east-1'],
+      fr: ['webservices.amazon.fr', 'eu-west-1'],
+      de: ['webservices.amazon.de', 'eu-west-1'],
+      in: ['webservices.amazon.in', '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'],
+      es: ['webservices.amazon.es', '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
+
+    # @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
 
-    def endpoint
-      "webservices.#{domain}"
-    end
+    private
 
-    def marketplace
-      "www.#{domain}"
-    end
+    def find_host_and_region(marketplace)
+      marketplace = marketplace.to_sym.downcase
+      marketplace = :gb if marketplace == :uk
 
-    def build_url(operation)
-      "https://#{endpoint}/paapi5/#{operation.downcase}"
+      HOSTS_AND_REGIONS.fetch(marketplace)
+    rescue KeyError
+      raise NotFound, "marketplace not found: :#{marketplace}"
     end
-
-    @all = [
-      [:au, 'amazon.com.au', 'us-west-2'],
-      [:br, 'amazon.com.br', 'us-east-1'],
-      [:ca, 'amazon.ca', 'us-east-1'],
-      [:fr, 'amazon.fr', 'eu-west-1'],
-      [:de, 'amazon.de', 'eu-west-1'],
-      [:in, 'amazon.in', 'eu-west-1'],
-      [:it, 'amazon.it', 'eu-west-1'],
-      [:jp, 'amazon.co.jp', 'us-west-2'],
-      [:mx, 'amazon.com.mx', 'us-east-1'],
-      [:es, 'amazon.es', 'eu-west-1'],
-      [:tr, 'amazon.com.tr', 'eu-west-1'],
-      [:ae, 'amazon.ae', 'eu-west-1'],
-      [:gb, 'amazon.co.uk', 'eu-west-1'],
-      [:us, 'amazon.com', 'us-east-1']
-    ].map { |attributes| new(*attributes) }
   end
 end

data/lib/vacuum/matcher.rb

@@ -4,20 +4,35 @@ require 'json'
 
 module Vacuum
   # Custom VCR matcher for stubbing calls to the Product Advertising API
-  # @api private
+  #
+  # 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

data/lib/vacuum/operation.rb

@@ -0,0 +1,75 @@
+# 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: url, body: 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,35 +1,35 @@
 # frozen_string_literal: true
 
-require 'aws-sigv4'
-require 'httpi'
-require 'json'
+require 'http'
 
 require 'vacuum/locale'
+require 'vacuum/operation'
 require 'vacuum/response'
 
 module Vacuum
   # A request to the Amazon Product Advertising API
   class Request
-    SERVICE = 'ProductAdvertisingAPI'
-    private_constant :SERVICE
+    # @return [HTTP::Client]
+    attr_reader :client
 
-    # @api private
-    attr_reader :access_key, :secret_key, :locale, :partner_tag, :partner_type
+    # @return [Locale]
+    attr_reader :locale
+
+    # @return [Operation]
+    attr_reader :operation
 
     # Creates a new request
-    # @param [Symbol,String] marketplace the two-letter country code of the
-    #   target Amazon locale
-    # @param [String] access_key your access key
-    # @param [String] secret_key your secret key
-    # @param [String] partner_tag your partner tag
-    # @param [String] partner_type your partner type
-    def initialize(marketplace: :us, access_key:, secret_key:, partner_tag:,
-                   partner_type: 'Associates')
-      @locale = Locale.find(marketplace)
-      @access_key = access_key
-      @secret_key = secret_key
-      @partner_tag = partner_tag
-      @partner_type = partner_type
+    #
+    # @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
@@ -119,69 +119,22 @@ module Vacuum
       request('SearchItems', params)
     end
 
-    private
-
-    def request(operation, params)
-      body = build_body(params)
-      signature = sign(operation, body)
-
-      request = HTTPI::Request.new(
-        headers: request_headers(operation, signature),
-        url: locale.build_url(operation),
-        body: body
-      )
-
-      Response.new(HTTPI.post(request))
-    end
-
-    def sign(operation, body)
-      signer.sign_request(
-        http_method: 'POST',
-        url: locale.build_url(operation),
-        headers: headers(operation),
-        body: body
-      )
+    # Creates a persistent connection for multiple requests
+    #
+    # @return [self]
+    def persistent
+      @client = client.persistent("https://#{locale.host}")
+      self
     end
 
-    def request_headers(operation, signature)
-      headers(operation).merge(
-        'Content-Type' => 'application/json; charset=utf-8',
-        'Authorization' => signature.headers['authorization'],
-        'X-Amz-Content-Sha256' => signature.headers['x-amz-content-sha256'],
-        'X-Amz-Date' => signature.headers['x-amz-date'],
-        'Host' => locale.endpoint
-      )
-    end
-
-    def headers(operation)
-      {
-        'X-Amz-Target' => "com.amazon.paapi5.v1.#{SERVICE}v1.#{operation}",
-        'Content-Encoding' => 'amz-1.0'
-      }
-    end
-
-    def signer
-      Aws::Sigv4::Signer.new(
-        service: SERVICE,
-        region: locale.region,
-        access_key_id: access_key,
-        secret_access_key: secret_key,
-        http_method: 'POST',
-        endpoint: locale.endpoint
-      )
-    end
-
-    def build_body(params)
-      hsh = { 'PartnerTag' => partner_tag,
-              'PartnerType' => partner_type }
+    private
 
-      params.each do |key, val|
-        key = key.to_s.split('_')
-                 .map { |word| word == 'asin' ? 'ASIN' : word.capitalize }.join
-        hsh[key] = val
-      end
+    def request(operation_name, params)
+      @operation = Operation.new(operation_name, params: params, locale: locale)
+      response = client.headers(operation.headers)
+                       .post(operation.url, body: operation.body)
 
-      JSON.generate(hsh)
+      Response.new(response)
     end
   end
 end