vacuum 2.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de7766702e1ee1d5084f61f8a337ff64b9e1210fd70167ee8e932b742eb522e5
-  data.tar.gz: b2a917e6f5d91bf0177471a65d319bc0d4438b773643d977f53c148d7d2f3770
+  metadata.gz: a4fabab10f086746082267c99d3c91d1b5efded68a7a39bac4e963125d1979d9
+  data.tar.gz: 8e8b4fc57cbd15da857f867b4ac3a0986a2664157047b0192272140c96a5475f
 SHA512:
-  metadata.gz: 276f630beba5150eb04b20c81ab9feb41db2488773e548da9d9f0df8c3b6a4197eb1948b84d467614de450b74e81023ef8ce5533abb03f4ebf8fec27a322b8a5
-  data.tar.gz: 87b683c87cb51462030f0ba2880e54e1b683723179a658f94dec92cad496b5ae5133c8cfd70b2844b187a108162adca3a3f4153cc5c45a5301826342e9040507
+  metadata.gz: 6075c9237d5b5556312e5afbce35d5e4cd573cf705de305e04ffa3e9a853202d6f4499937f991eda1c65c33a84c5e8625f043eb391161fd96e4a827aa9f6f5a5
+  data.tar.gz: e031688b51fed66acd8b8442e2475c1b0d6ec7ed991e74e6df63c427017407da0799cbca46baa0a496b480fd9725d80f8e5ad379fb872c4448d6fd43bc419621

data/README.md

@@ -1,211 +1,179 @@
 # Vacuum
-[![Travis](https://travis-ci.org/hakanensari/vacuum.svg)](https://travis-ci.org/hakanensari/vacuum)
 
-Vacuum is a fast, light-weight Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html).
+[![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](http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png)
+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.
 
-## Usage
+Cart Form functionality is not covered by this gem but is a primary focus on [carriage gem](https://github.com/skatkov/carriage)
 
-Refer to the [API docs](https://docs.aws.amazon.com/AWSECommerceService/latest/DG/CHAP_ApiReference.html) as necessary.
+You need to [register first](https://webservices.amazon.com/paapi5/documentation/register-for-pa-api.html) to use the API.
 
-### Prerequisite
+![vacuum](http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png)
 
-You must [register as an affiliate](https://affiliate-program.amazon.com) to access the API. Amazon will issue your AWS credentials when you register.
+## Usage
 
-### Setup
+### Getting Started
 
-Create a request:
+Create a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.
 
 ```ruby
-request = Vacuum.new
+request = Vacuum.new(marketplace: 'US',
+                     access_key: '<ACCESS_KEY>',
+                     secret_key: '<SECRET_KEY>',
+                     partner_tag: '<PARTNER_TAG>')
 ```
 
-The locale will default to the US. To use another locale, reference its two-letter country code:
+You can now access the API using the available operations.
 
 ```ruby
-request = Vacuum.new('GB')
+response = request.search_items(title: 'lean startup')
+puts response.to_h
 ```
 
-Configure the request credentials:
+Create a persistent connection to make multiple requests.
 
 ```ruby
-request.configure(
-  aws_access_key_id: 'key',
-  aws_secret_access_key: 'secret',
-  associate_tag: 'tag'
-)
+request.persistent
 ```
 
-You can omit the above if you set your key and secret as environment variables:
+### Operations
 
-```sh
-export AWS_ACCESS_KEY_ID=key
-export AWS_SECRET_ACCESS_KEY=secret
-```
+Refer to the [API docs](https://webservices.amazon.com/paapi5/documentation/) for more detailed information.
 
-You will still need to set an associate tag:
+#### 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.
 
 ```ruby
-request.associate_tag = 'tag'
+request.get_browse_nodes(
+  browse_node_ids: ['283155', '3040'],
+  resources: ['BrowseNodes.Ancestor', 'BrowseNodes.Children']
+)
 ```
 
-Provided you are looking to earn commission, you have to register independently with each locale you query. Otherwise, you may reuse any dummy associate tag.
+#### GetItems
 
-The API version defaults to `2013-08-01`. To use another version, reference its date string:
+Given an Item identifier, the `GetItems` operation returns the item attributes, based on the resources specified in the request.
 
 ```ruby
-request.version = '2011-08-01'
+request.get_items(
+  item_ids: ['B0199980K4', 'B000HZD168', 'B01180YUXS', 'B00BKQTA4A'],
+  resources: ['Images.Primary.Small', 'ItemInfo.Title', 'ItemInfo.Features',
+              'Offers.Summaries.HighestPrice' , 'ParentASIN']
+)
 ```
 
-### Request
+#### GetVariations
 
-#### Browse Node Lookup
-
-**BrowseNodeLookup** returns a specified browse node’s name and ancestors:
+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.
 
 ```ruby
-response = request.browse_node_lookup(
-  query: {
-    'BrowseNodeId' => 123
-  }
+request.get_variations(
+  asin: 'B00422MCUS',
+  resources: ['ItemInfo.Title', 'VariationSummary.Price.HighestPrice',
+              'VariationSummary.Price.LowestPrice',
+              'VariationSummary.VariationDimension']
 )
 ```
 
-#### Cart Operations
+#### SearchItems
 
-The **CartCreate** operation creates a remote shopping cart:
+The `SearchItems` operation searches for items on Amazon based on a search query. The API returns up to ten items per search request.
 
 ```ruby
-response = request.cart_create(
-  query: {
-    'HMAC' => 'secret',
-    'Item.1.OfferListingId' => '123',
-    'Item.1.Quantity' => 1
-  }
-)
+request.search_items(keywords: 'harry potter')
 ```
 
-The **CartAdd** operation adds items to an existing remote shopping cart:
+### Response
+
+Consume a response by parsing it into a Ruby hash.
 
 ```ruby
-response = request.cart_add(
-  query: {
-    'CartId' => '123',
-    'HMAC' => 'secret',
-    'Item.1.OfferListingId' => '123',
-    'Item.1.Quantity' => 1
-  }
-)
+response.to_h
 ```
 
-The **CartClear** operation removes all of the items in a remote shopping cart:
+You can also `#dig` into this hash.
 
 ```ruby
-response = request.cart_clear(
-  query: {
-    'CartId' => '123',
-    'HMAC' => 'secret'
-  }
-)
+response.dig('ItemsResult', 'Items')
 ```
 
-The **CartGet** operation retrieves the IDs, quantities, and prices of the items, including SavedForLater ones, in a remote shopping cart:
+### 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
-response = request.cart_get(
-  query: {
-    'CartId' => '123',
-    'HMAC' => 'secret',
-    'CartItemId' => '123'
-  }
-)
-```
+require 'logger'
 
-#### Item Lookup
+logger = Logger.new(STDOUT)
+request.use(logging: {logger: logger})
+```
 
-The **ItemLookup** operation returns some or all of the attributes of an item, depending on the response group specified in the request. By default, the operation returns an item’s ASIN, manufacturer, product group, and title.
+### 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
-response = request.item_lookup(
-  query: {
-    'ItemId' => '0679753354'
-  }
-)
+response.parser = MyParser
+response.parse
 ```
 
-#### Item Search
+If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.
+
+### VCR
 
-The **ItemSearch** operation returns items that satisfy the search criteria, including one or more search indices.
+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
-response = request.item_search(
-  query: {
-    'Keywords' => 'Architecture',
-    'SearchIndex' => 'Books'
-  }
-)
-```
+require 'vacuum/matcher'
 
-#### Similarity Lookup
+# in your test
+VCR.insert_cassette('cassette_name',
+                    match_requests_on: [Vacuum::Matcher])
+```
 
-The **SimilarityLookup** operation returns up to ten products per page that are similar to one or more items specified in the request. This operation is typically used to pique a customer’s interest in buying something similar to what they’ve already ordered.
+In RSpec, use the `:paapi` metadata.
 
 ```ruby
-response = request.similarity_lookup(
-  query: {
-    'ItemId' => '0679753354'
-  }
-)
-```
+require 'vacuum/matcher'
 
-#### Configuring a request
+# in your test
+it 'queries Amazon', :paapi do
+end
+```
 
-Vacuum wraps [Excon](https://github.com/geemus/excon). Use the latter's API to tweak your request.
+## Development
 
-For example, to use a persistent connection:
+Clone the repo and install dependencies.
 
-```ruby
-response = request.item_search(
-  query: {
-    'ItemId' => '0679753354'
-  },
-  persistent: true
-)
+```sh
+bundle install
 ```
 
-### Response
-
-The quick and dirty way to consume a response is to parse into a Ruby hash:
+Tests and Rubocop should now pass as-is.
 
-```ruby
-response.to_h
+```sh
+bundle exec rake
 ```
 
-You can also `#dig` into returned Hash:
+By default, the tests stub requests. Use the `RECORD` env var to record new interactions.
 
-```ruby
-response.dig('ItemSearchResponse', 'Items', 'Item')
+```sh
+RECORD=true bundle exec rake test
 ```
 
-In production, you may prefer to use a custom parser to do some XML heavy-lifting:
+You can set the `LIVE` env var to run all tests against live data.
 
-```ruby
-class MyParser
-  # A parser has to respond to this.
-  def self.parse(body)
-    new(body)
-  end
+```sh
+LIVE=true bundle exec rake test
+```
 
-  def initialize(body)
-    @body = body
-  end
+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`.
 
-  # Implement parser here.
-end
+## Getting Help
+
+* Ask specific questions about the API on the [Amazon forum](https://forums.aws.amazon.com/forum.jspa?forumID=9).
+* Report bugs and discuss potential features in [GitHub issues](https://github.com/hakanensari/vacuum/issues).
 
-response.parser = MyParser
-response.parse
-```
 
-If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.

data/lib/vacuum.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 require 'forwardable'
+
 require 'vacuum/request'
 require 'vacuum/version'
 
-# Vacuum is a Ruby wrapper to the Amazon Product Advertising API.
+# Ruby wrapper to the Amazon Product Advertising API
 module Vacuum
   class << self
     extend Forwardable
 
-    def_delegator Vacuum::Request, :new
+    # @!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

@@ -0,0 +1,64 @@
+# 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'],
+      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
+
+    # @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

@@ -0,0 +1,71 @@
+# 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
+
+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