vacuum 3.0.0 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f97f47ef585594e52efc75ac3824e47992ad0ac6cbd688f05363579c9feff3
-  data.tar.gz: 4d0399b9b897cd955cb3c2739a3b2fcb4e393c6ee092270d21d28dab8ee503fc
+  metadata.gz: 61ab29cce33477553968b592986abbc5de22f4885945032313a08dc89174c5c4
+  data.tar.gz: 01b3fddbc4f06899df06c595ff28dc0f812cca8d1b8604771614a077129d4a99
 SHA512:
-  metadata.gz: eac6cca761cd2ccc75e7eb9d626398505c06400116efe5bb765e5112debb0f3b22da3dab840aa1bbde19de752d841bd836029c6c1bb7f3b12738d74bfecd0e3b
-  data.tar.gz: 8571a8e9c4b64b71038bf7713364c8b56bca14bb08abae6743aaf2cea0a976fe1b0025432ad659b300d8d5763deb05bd9ff4200bdfcb80e52de9a2f3d3e8952c
+  metadata.gz: b0d2aeb0b372920cca1f68268fe91f80630ca7272e1a6dadb25677aacad9a6ae86fa3ec2056ec5419f3167c2871ed9ffaf4a37dc248b8d0bc50ce51599a08e9a
+  data.tar.gz: 423a1e7ccd04499c3df8a05dde1da3a25f691ef4d846f64bd59ac55af55f9783239efdd537881a0c460900cad326fdd4c50041e0ce7bb9233cd3c934861227ba

data/README.md

@@ -1,20 +1,22 @@
 # 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)
+[![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 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.
+
+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](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 +25,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
-HTTPI.adapter = :http
+response = request.search_items(title: 'lean startup')
+puts response.to_h
+```
+
+Create a persistent connection to make multiple requests.
+
+```ruby
+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 +80,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,18 +88,30 @@ 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')
 ```
 
+### 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`.
 
 ```ruby
@@ -98,37 +121,55 @@ response.parse
 
 If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.
 
-### VCR Support
+### VCR
 
-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.
+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'
 
-VCR.insert_cassette('paapi', match_requests_on: [Vacuum::Matcher])
+# in your test
+VCR.insert_cassette('cassette_name',
+                    match_requests_on: [Vacuum::Matcher])
 ```
 
-## Testing
+In RSpec, use the `:paapi` metadata.
+
+```ruby
+require 'vacuum/matcher'
+
+# in your test
+it 'queries Amazon', :paapi do
+end
+```
 
-Tests should pass as-is once you install dependencies.
+## Development
+
+Clone the repo and install dependencies.
+
+```sh
+bundle install
+```
+
+Tests and Rubocop should now 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, the tests stub requests. Use the `RECORD` env var to record new interactions.
 
 ```sh
-bundle exec RECORD=true rake
+RECORD=true bundle exec rake test
 ```
 
-You can also run tests against live data.
+You can set the `LIVE` env var to run all tests against live data.
 
-```shell
-bundle exec LIVE=true rake
+```sh
+LIVE=true bundle exec rake test
 ```
 
-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,64 @@
 # 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
+    # Raised when the provided marketplace does not correspond to an existing
+    # Amazon locale
+    class NotFound < KeyError; end
 
-    attr_reader :code, :domain, :region
+    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'],
+      nl: ['webservices.amazon.nl', 'eu-west-1'],
+      sg: ['webservices.amazon.sg', 'us-west-2'],
+      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
+    private_constant :HOSTS_AND_REGIONS
 
-    def self.find(code)
-      code = code.to_sym.downcase
-      code = :gb if code == :uk
+    # @return [String]
+    attr_reader :host, :region, :access_key, :secret_key, :partner_tag,
+                :partner_type
 
-      @all.find { |locale| locale.code == code } || raise(NotFound)
+    # 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 initialize(code, domain, region)
-      @code = code
-      @domain = domain
-      @region = region
-    end
+    private
 
-    def endpoint
-      "webservices.#{domain}"
-    end
+    def find_host_and_region(marketplace)
+      marketplace = marketplace.to_sym.downcase
+      marketplace = :gb if marketplace == :uk
 
-    def marketplace
-      "www.#{domain}"
+      HOSTS_AND_REGIONS.fetch(marketplace)
+    rescue KeyError
+      raise NotFound, "marketplace not found: :#{marketplace}"
     end
-
-    def build_url(operation)
-      "https://#{endpoint}/paapi5/#{operation.downcase}"
-    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
@@ -38,3 +53,21 @@ module Vacuum
     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

@@ -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,38 +1,39 @@
 # 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
+    #
     # @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
@@ -48,6 +49,7 @@ module Vacuum
     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
@@ -69,6 +71,7 @@ module Vacuum
 
     # 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
@@ -89,6 +92,7 @@ module Vacuum
     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
@@ -119,69 +123,51 @@ module Vacuum
       request('SearchItems', params)
     end
 
-    private
-
-    def request(operation, params)
-      body = build_body(params)
-      signature = sign(operation, body)
+    # Flags as persistent
+    #
+    # @param [Integer] timeout
+    # @return [self]
+    def persistent(timeout: 5)
+      host = "https://#{locale.host}"
+      @client = client.persistent(host, timeout: timeout)
 
-      request = HTTPI::Request.new(
-        headers: request_headers(operation, signature),
-        url: locale.build_url(operation),
-        body: body
-      )
-
-      Response.new(HTTPI.post(request))
+      self
     end
 
-    def sign(operation, body)
-      signer.sign_request(
-        http_method: 'POST',
-        url: locale.build_url(operation),
-        headers: headers(operation),
-        body: body
-      )
+    # @!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
 
-    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
+    private
 
-    def headers(operation)
-      {
-        'X-Amz-Target' => "com.amazon.paapi5.v1.#{SERVICE}v1.#{operation}",
-        'Content-Encoding' => 'amz-1.0'
-      }
-    end
+    def validate_keywords(params)
+      return unless params[:keywords]
+      return if params[:keywords].is_a?(String)
 
-    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
-      )
+      raise ArgumentError, ':keyword argument expects a String'
     end
 
-    def build_body(params)
-      hsh = { 'PartnerTag' => partner_tag,
-              'PartnerType' => partner_type }
-
-      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)
+      validate_keywords(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