vacuum 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1b71a457cf1479084393d842f764c235df227e69df803d3831a61ad58c17e58
-  data.tar.gz: 58f3653a02464e6c84d2bb6eca1b5ef1d38beef082c08586850fd2819411e2e6
+  metadata.gz: a4fabab10f086746082267c99d3c91d1b5efded68a7a39bac4e963125d1979d9
+  data.tar.gz: 8e8b4fc57cbd15da857f867b4ac3a0986a2664157047b0192272140c96a5475f
 SHA512:
-  metadata.gz: 78da469aa7084427b691489bfc180f280cd3dab342665d1ce4b8df5cb996b497a5344bd764fa8122f25a37f9df080580b4057ce70287982654b18b9032a2bc17
-  data.tar.gz: 6a5bdede32ec18b191e1204b7fad7a5559ddeed01ab4316131b8349ca8037528612a9c6b0f56f6579e986e85ec644cbfa35c65663129406854dc62ec200f1eca
+  metadata.gz: 6075c9237d5b5556312e5afbce35d5e4cd573cf705de305e04ffa3e9a853202d6f4499937f991eda1c65c33a84c5e8625f043eb391161fd96e4a827aa9f6f5a5
+  data.tar.gz: e031688b51fed66acd8b8442e2475c1b0d6ec7ed991e74e6df63c427017407da0799cbca46baa0a496b480fd9725d80f8e5ad379fb872c4448d6fd43bc419621

data/README.md

@@ -6,6 +6,8 @@
 
 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)
@@ -98,15 +100,15 @@ You can also `#dig` into this hash.
 response.dig('ItemsResult', 'Items')
 ```
 
-### Troubleshooting
+### Logging
 
-In addition to the response payload, the following attributes may help you introspect an executed request.
+Write requests and reponses to a logger using the logging feature of the [HTTP gem](https://github.com/httprb/http) under the hood:
 
 ```ruby
-operation = request.operation
-operation.body
-operation.headers
-operation.url
+require 'logger'
+
+logger = Logger.new(STDOUT)
+request.use(logging: {logger: logger})
 ```
 
 ### Bring your parser
@@ -131,25 +133,11 @@ VCR.insert_cassette('cassette_name',
                     match_requests_on: [Vacuum::Matcher])
 ```
 
-In RSpec, consider using custom metadata.
+In RSpec, use the `:paapi` metadata.
 
 ```ruby
 require '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
@@ -157,22 +145,28 @@ end
 
 ## Development
 
-Clone the repo and install dependencies. Tests should pass as-is.
+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 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, add actual API credentials to a [`locales.yml`](https://github.com/hakanensari/vacuum/blob/master/test/locales.yml.example) file under `test`.

data/lib/vacuum/locale.rb

@@ -19,6 +19,7 @@ module Vacuum
       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'],

data/lib/vacuum/matcher.rb

@@ -53,3 +53,19 @@ module Vacuum
     end
   end
 end
+
+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

data/lib/vacuum/request.rb

@@ -4,6 +4,7 @@ require 'http'
 
 require 'vacuum/locale'
 require 'vacuum/operation'
+require 'vacuum/resource'
 require 'vacuum/response'
 
 module Vacuum
@@ -33,6 +34,7 @@ module Vacuum
     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 +50,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 +72,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 +93,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,17 +124,61 @@ module Vacuum
       request('SearchItems', params)
     end
 
-    # Creates a persistent connection for multiple requests
+    # Flags as persistent
     #
+    # @param [Integer] timeout
     # @return [self]
-    def persistent
-      @client = client.persistent("https://#{locale.host}")
+    def persistent(timeout: 5)
+      host = "https://#{locale.host}"
+      @client = client.persistent(host, timeout: 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(params)
+      validate_keywords(params)
+      validate_resources(params)
+    end
+
+    def validate_keywords(params)
+      return unless params[:keywords]
+      return if params[:keywords].is_a?(String)
+
+      raise ArgumentError, ':keyword argument expects a String'
+    end
+
+    def validate_resources(params)
+      return unless params[:resources]
+
+      raise ArgumentError, ':resources argument expects an Array' unless params[:resources].is_a?(Array)
+
+      params[:resources].each do |resource|
+        raise ArgumentError, "There is not such resource: #{resource}" unless Resource.valid?(resource)
+      end
+    end
+
     def request(operation_name, params)
+      validate(params)
       @operation = Operation.new(operation_name, params: params, locale: locale)
       response = client.headers(operation.headers)
                        .post(operation.url, body: operation.body)

data/lib/vacuum/resource.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Vacuum
+  # Resources determine what information will be returned in the API response
+  #
+  # @see https://webservices.amazon.com/paapi5/documentation/resources.html
+  class Resource
+    ALL = %w[BrowseNodeInfo.BrowseNodes
+             BrowseNodeInfo.BrowseNodes.Ancestor
+             BrowseNodeInfo.BrowseNodes.SalesRank
+             BrowseNodeInfo.WebsiteSalesRank
+             Images.Primary.Small
+             Images.Primary.Medium
+             Images.Primary.Large
+             Images.Variants.Small
+             Images.Variants.Medium
+             Images.Variants.Large
+             ItemInfo.ByLineInfo
+             ItemInfo.Classifications
+             ItemInfo.ContentInfo
+             ItemInfo.ContentRating
+             ItemInfo.ExternalIds
+             ItemInfo.Features
+             ItemInfo.ManufactureInfo
+             ItemInfo.ProductInfo
+             ItemInfo.TechnicalInfo
+             ItemInfo.Title
+             ItemInfo.TradeInInfo
+             Offers.Listings.Availability.MaxOrderQuantity
+             Offers.Listings.Availability.Message
+             Offers.Listings.Availability.MinOrderQuantity
+             Offers.Listings.Availability.Type
+             Offers.Listings.Condition
+             Offers.Listings.Condition.SubCondition
+             Offers.Listings.DeliveryInfo.IsAmazonFulfilled
+             Offers.Listings.DeliveryInfo.IsFreeShippingEligible
+             Offers.Listings.DeliveryInfo.IsPrimeEligible
+             Offers.Listings.IsBuyBoxWinner
+             Offers.Listings.LoyaltyPoints.Points
+             Offers.Listings.MerchantInfo
+             Offers.Listings.Price
+             Offers.Listings.ProgramEligibility.IsPrimeExclusive
+             Offers.Listings.ProgramEligibility.IsPrimePantry
+             Offers.Listings.Promotions
+             Offers.Listings.SavingBasis
+             Offers.Summaries.HighestPrice
+             Offers.Summaries.LowestPrice
+             Offers.Summaries.OfferCount
+             ParentASIN].freeze
+    private_constant :ALL
+
+    # @!attribute [r] all
+    # @return [Array<String>]
+    def self.all
+      ALL
+    end
+
+    def self.valid?(resource)
+      ALL.include?(resource)
+    end
+  end
+end

data/lib/vacuum/response.rb

@@ -12,6 +12,7 @@ module Vacuum
     # @!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
@@ -38,6 +39,7 @@ module Vacuum
     end
 
     # Casts body to Hash
+    #
     # @return [Hash]
     def to_h
       JSON.parse(body)

data/lib/vacuum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vacuum
-  VERSION = '3.3.0'
+  VERSION = '3.4.0'
 end

data/test/integration/test_requests.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'integration_helper'
+
+module Vacuum
+  class TestRequests < IntegrationTest
+    def test_get_browse_nodes
+      requests.each do |request|
+        response = request.get_browse_nodes(browse_node_ids: ['3045'])
+        assert_equal 200, response.status
+      end
+    end
+
+    def test_get_items
+      requests.each do |request|
+        response = request.get_items(item_ids: ['B07212L4G2'])
+        assert_equal 200, response.status
+      end
+    end
+
+    def test_get_items_with_all_resources
+      requests.each do |request|
+        response = request.get_items(item_ids: 'B07212L4G2',
+                                     resources: Resource.all)
+        assert_equal 200, response.status
+        item = response.dig('ItemsResult', 'Items').first
+        assert item.key?('BrowseNodeInfo')
+      end
+    end
+
+    def test_get_variations
+      requests.each do |request|
+        response = request.get_variations(asin: 'B07212L4G2')
+        assert_equal 200, response.status
+      end
+    end
+
+    def test_search_items
+      requests.each do |request|
+        response = request.search_items(keywords: 'Harry Potter')
+        assert_equal 200, response.status
+      end
+    end
+
+    def test_persistent
+      request = requests.sample
+      refute request.client.persistent?
+      request.persistent
+      assert request.client.persistent?
+    end
+
+    def test_logging
+      require 'logger'
+      logdev = StringIO.new
+      logger = Logger.new(logdev)
+      request = requests.sample
+      request.use(logging: { logger: logger })
+      request.search_items(keywords: 'Harry Potter')
+      refute_empty logdev.string
+    end
+  end
+end

data/test/unit/test_request.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'helper'
+require 'vacuum/request'
+
+module Vacuum
+  class TestRequest < Minitest::Test
+    def test_search_keywords
+      err = assert_raises(ArgumentError) do
+        api.search_items(keywords: ['Harry Potter'])
+      end
+
+      assert_equal ':keyword argument expects a String', err.message
+    end
+
+    def test_search_resources
+      err = assert_raises(ArgumentError) do
+        api.search_items(
+          keywords: 'Harry Potter',
+          resources: %w[Images.Primary.Large ItemInfo.ExternalIds Offer.Listings.Price]
+        )
+      end
+
+      assert_equal 'There is not such resource: Offer.Listings.Price', err.message
+    end
+
+    def test_get_items_wrong_resource
+      err = assert_raises(ArgumentError) do
+        api.get_items(
+          item_ids: :B07212L4G2,
+          resources: %w[BrowseNodeInfo.BrowseNode.SalesRank]
+        )
+      end
+
+      assert_equal 'There is not such resource: BrowseNodeInfo.BrowseNode.SalesRank', err.message
+    end
+
+    def test_get_variations_wrong_resource
+      err = assert_raises(ArgumentError) do
+        api.get_variations(asin: 'B07212L4G2', resources: %w[BrowseNodeInfo.BrowseNode.SalesRank])
+      end
+
+      assert_equal 'There is not such resource: BrowseNodeInfo.BrowseNode.SalesRank', err.message
+    end
+
+    def test_resource_not_array
+      err = assert_raises(ArgumentError) do
+        api.get_items(item_ids: :B07212L4G2, resources: 'foo')
+      end
+
+      assert_equal ':resources argument expects an Array', err.message
+    end
+
+    def api
+      @api ||= Vacuum::Request.new(marketplace: 'US',
+                                   access_key: 'key',
+                                   secret_key: 'secret',
+                                   partner_tag: 'tag')
+    end
+  end
+end

data/test/unit/test_resource.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'helper'
+require 'vacuum/resource'
+
+module Vacuum
+  class TestResource < Minitest::Test
+    def test_all
+      refute_empty Resource.all
+    end
+  end
+end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: vacuum
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Hakan Ensari
+- Stanislav Katkov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-26 00:00:00.000000000 Z
+date: 2020-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sigv4
@@ -84,16 +85,16 @@ dependencies:
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.17.1
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -139,6 +140,7 @@ dependencies:
 description: A wrapper to the Amazon Product Advertising API
 email:
 - me@hakanensari.com
+- sk@skylup.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -150,18 +152,21 @@ files:
 - lib/vacuum/matcher.rb
 - lib/vacuum/operation.rb
 - lib/vacuum/request.rb
+- lib/vacuum/resource.rb
 - lib/vacuum/response.rb
 - lib/vacuum/version.rb
 - test/cassettes/vacuum.yml
 - test/helper.rb
+- test/integration/test_requests.rb
 - test/integration_helper.rb
 - test/locales.rb
 - test/locales.yml
 - test/locales.yml.example
-- test/vacuum/test_locale.rb
-- test/vacuum/test_operation.rb
-- test/vacuum/test_request.rb
-- test/vacuum/test_response.rb
+- test/unit/test_locale.rb
+- test/unit/test_operation.rb
+- test/unit/test_request.rb
+- test/unit/test_resource.rb
+- test/unit/test_response.rb
 homepage: https://github.com/hakanensari/vacuum
 licenses:
 - MIT
@@ -174,7 +179,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -186,11 +191,13 @@ signing_key:
 specification_version: 4
 summary: Amazon Product Advertising in Ruby
 test_files:
+- test/unit/test_operation.rb
+- test/unit/test_request.rb
+- test/unit/test_resource.rb
+- test/unit/test_response.rb
+- test/unit/test_locale.rb
 - test/helper.rb
-- test/vacuum/test_operation.rb
-- test/vacuum/test_request.rb
-- test/vacuum/test_response.rb
-- test/vacuum/test_locale.rb
+- test/integration/test_requests.rb
 - test/cassettes/vacuum.yml
 - test/integration_helper.rb
 - test/locales.rb

data/test/vacuum/test_request.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-require 'integration_helper'
-
-module Vacuum
-  class TestRequest < IntegrationTest
-    def test_get_browse_nodes
-      requests.each do |request|
-        response = request.get_browse_nodes(browse_node_ids: ['3045'])
-        assert_equal 200, response.status
-      end
-    end
-
-    def test_get_items
-      requests.each do |request|
-        response = request.get_items(item_ids: ['B07212L4G2'])
-        assert_equal 200, response.status
-      end
-    end
-
-    def test_get_items_with_all_resources
-      requests.each do |request|
-        response = request.get_items(item_ids: 'B07212L4G2',
-                                     resources: ALL_RESOURCES)
-        item = response.dig('ItemsResult', 'Items').first
-        assert item.key?('BrowseNodeInfo')
-      end
-    end
-
-    def test_get_variations
-      requests.each do |request|
-        response = request.get_variations(asin: 'B07212L4G2')
-        assert_equal 200, response.status
-      end
-    end
-
-    def test_search_items
-      requests.each do |request|
-        response = request.search_items(keywords: 'Harry Potter')
-        assert_equal 200, response.status
-      end
-    end
-
-    def test_persistent
-      request = requests.sample
-      refute request.client.persistent?
-      request.persistent
-      assert request.client.persistent?
-    end
-
-    ALL_RESOURCES =
-      %w[BrowseNodeInfo.BrowseNodes BrowseNodeInfo.BrowseNodes.Ancestor
-         BrowseNodeInfo.BrowseNodes.SalesRank BrowseNodeInfo.WebsiteSalesRank
-         Images.Primary.Small Images.Primary.Medium Images.Primary.Large
-         Images.Variants.Small Images.Variants.Medium Images.Variants.Large
-         ItemInfo.ByLineInfo ItemInfo.Classifications ItemInfo.ContentInfo
-         ItemInfo.ContentRating ItemInfo.ExternalIds ItemInfo.Features
-         ItemInfo.ManufactureInfo ItemInfo.ProductInfo ItemInfo.TechnicalInfo
-         ItemInfo.Title ItemInfo.TradeInInfo
-         Offers.Listings.Availability.MaxOrderQuantity
-         Offers.Listings.Availability.Message
-         Offers.Listings.Availability.MinOrderQuantity
-         Offers.Listings.Availability.Type Offers.Listings.Condition
-         Offers.Listings.Condition.SubCondition
-         Offers.Listings.DeliveryInfo.IsAmazonFulfilled
-         Offers.Listings.DeliveryInfo.IsFreeShippingEligible
-         Offers.Listings.DeliveryInfo.IsPrimeEligible
-         Offers.Listings.IsBuyBoxWinner Offers.Listings.LoyaltyPoints.Points
-         Offers.Listings.MerchantInfo Offers.Listings.Price
-         Offers.Listings.ProgramEligibility.IsPrimeExclusive
-         Offers.Listings.ProgramEligibility.IsPrimePantry
-         Offers.Listings.Promotions Offers.Listings.SavingBasis
-         Offers.Summaries.HighestPrice Offers.Summaries.LowestPrice
-         Offers.Summaries.OfferCount ParentASIN].freeze
-    private_constant :ALL_RESOURCES
-  end
-end