vacuum 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5e4bd6227abb1fea07adb3e354bad09a688b86f7
-  data.tar.gz: c422eef181619b91410a1adb2568de0622da0744
+  metadata.gz: 99bd9a237d04b447017964b0b8f672d95f2d06ba
+  data.tar.gz: 7cca17378340136b4af9d4038b26822b7e07e3e3
 SHA512:
-  metadata.gz: a4427bfcdfff025d95dc70084afd7c9af29e5de0c5e64bae4cebf7f09634881890544dee2adcaaffb327a712dd4e331e4b56284c17db9e1dbb5ac1e89e46faa6
-  data.tar.gz: 6b2a8f8fffdf7b003252b9014744050223c7b6835797d860b737668a9f79aac902f0fb268cf8b271fbe162eacbc5bedb204b83a83d7da90ad201b34dab60efa3
+  metadata.gz: d6162aca52ed85ae0ee728d0fcd7cb21269e316478fe685e401c1181793e039bf85cf72dc5099772f43deaf51965623ceb3e2fae1e31e56f9aaa0c83ff562b47
+  data.tar.gz: 9cab62d3c97f2a6f0d604d0d32d454ac4d58fea793b3977bdf8352746273bb20a55cb66adebe69c2575c76dc0caaa7d9c7d951f09c07fcd431b3c932c2aa9222

data/README.md

@@ -1,96 +1,193 @@
 # Vacuum
+[![Travis](https://travis-ci.org/hakanensari/vacuum.svg)](https://travis-ci.org/hakanensari/vacuum)
 
-[![Build Status][1]][2]
+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).
 
-Vacuum is a fast, light-weight Ruby wrapper to the [Amazon Product Advertising API][4].
-
-![vacuum][3]
+![vacuum](http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png)
 
 ## Usage
 
 ### Setup
 
-Set up a request:
+Create a request:
 
 ```ruby
-req = Vacuum.new
+request = Vacuum.new
 ```
 
-The locale defaults to the US. To use another locale, instantiate with its
-two-letter country code:
+The locale will default to the US. To use another locale, reference its two-letter country code:
 
 ```ruby
-req = Vacuum.new('GB')
+request = Vacuum.new('GB')
 ```
 
 Configure the request credentials:
 
 ```ruby
-req.configure(
-    aws_access_key_id:     'key',
+request.configure(
+    aws_access_key_id: 'key',
     aws_secret_access_key: 'secret',
-    associate_tag:         'tag'
+    associate_tag: 'tag'
 )
 ```
 
-Alternatively, set the key and secret as environment variables globally:
+You can omit the above if you set your key and secret as environment variables:
 
 ```sh
 export AWS_ACCESS_KEY_ID=key
 export AWS_SECRET_ACCESS_KEY=secret
 ```
 
-You will still need to set a distinct associate tag for each locale:
+You will still need to set an associate tag:
 
 ```ruby
-req.associate_tag = 'tag'
+request.associate_tag = 'tag'
 ```
 
+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.
+
 ### Request
 
-Set up your parameters and make a request:
+#### Browse Node Lookup
+
+**BrowseNodeLookup** returns a specified browse node’s name and ancestors:
 
 ```ruby
-params = {
-  'SearchIndex' => 'Books',
-  'Keywords'    => 'Architecture'
-}
-res = req.item_search(query: params)
+response = request.browse_node_lookup(
+  query: {
+    'BrowseNodeId' => 123
+  }
+)
 ```
-The above executes an item search operation. The names of available methods
-derive from the operations listed in the API docs and include
-`browse_node_lookup`, `cart_add`, `cart_clear`, `cart_create`, `cart_get`,
-`cart_modify`, `item_lookup`, `item_search`, and `similarity_lookup`.
 
-Vacuum uses [Excon][5] as HTTP client. Check the Excon API for ways to tweak
-your request:
+#### Cart Operations
+
+The **CartCreate** operation creates a remote shopping cart:
 
 ```ruby
-res = req.item_search(query: params, persistent: true)
+response = request.cart_create(
+  query: {
+    'HMAC' => 'secret',
+    'Item.1.OfferListingId' => '123',
+    'Item.1.Quantity' => 1
+  }
+)
 ```
 
-### Response
+The **CartAdd** operation adds items to an existing remote shopping cart:
+
+```ruby
+response = request.cart_add(
+  query: {
+    'CartId' => '123',
+    'HMAC' => 'secret',
+    'Item.1.OfferListingId' => '123',
+    'Item.1.Quantity' => 1
+  }
+)
+```
+
+The **CartClear** operation removes all of the items in a remote shopping cart:
+
+```ruby
+response = request.cart_clear(
+  query: {
+    'CartId' => '123',
+    'HMAC' => 'secret'
+  }
+)
+```
+
+The **CartGet** operation retrieves the IDs, quantities, and prices of the items, including SavedForLater ones, in a remote shopping cart:
+
+```ruby
+response = request.cart_get(
+  query: {
+    'CartId' => '123',
+    'HMAC' => 'secret',
+    'CartItemId' => '123'
+  }
+)
+```
+
+#### Item Lookup
+
+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.
+
+```ruby
+response = request.item_lookup(
+  query: {
+    'ItemId' => '0679753354'
+  }
+)
+```
 
-The quickest way to consume a response is to parse it into a Ruby hash:
+#### Item Search
+
+The **ItemSearch** operation returns items that satisfy the search criteria, including one or more search indices.
 
 ```ruby
-res.to_h
+response = request.item_search(
+  query: {
+    'Keywords'    => 'Architecture',
+    'SearchIndex' => 'Books'
+  }
+)
 ```
 
-Vacuum uses [MultiXml][6], which will work with a number of popular XML
-libraries. If working in MRI, you may want to use [Ox][7].
+#### Similarity Lookup
 
-You can also pass the response body into your own parser for some custom XML
-heavy-lifting:
+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.
 
 ```ruby
-MyParser.new(res.body)
+response = request.similarity_lookup(
+  query: {
+    'ItemId'    => '0679753354'
+  }
+)
+```
+
+#### Configuring a request
+
+Vacuum wraps [Excon](https://github.com/geemus/excon). Use the latter's API to tweak your request.
+
+For example, to use a persistent connection:
+
+```ruby
+response = request.item_search(
+  query: {
+    'ItemId' => '0679753354'
+  },
+  persistent: true
+)
+```
+
+### Response
+
+The quick and dirty way to consume a response is to parse it into a Ruby hash:
+
+```ruby
+response.to_h
+```
+
+In production, you may prefer to use a custom parser to do some XML heavy-lifting:
+
+```ruby
+class MyParser
+  # A parser has to respond to this.
+  def self.parse(body)
+    new(body)
+  end
+
+  def initialize(body)
+    @body = body
+  end
+
+  # Implement parser here.
+end
+
+response.parser = MyParser
+response.parse
 ```
 
-[1]: https://secure.travis-ci.org/hakanensari/vacuum.png
-[2]: http://travis-ci.org/hakanensari/vacuum
-[3]: http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png
-[4]: https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html
-[5]: https://github.com/geemus/excon
-[6]: https://github.com/sferik/multi_xml
-[7]: https://github.com/ohler55/ox
+If no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.

data/lib/vacuum/request.rb

@@ -48,7 +48,7 @@ module Vacuum
     #
     # Raises a Bad Locale error if locale is not valid.
     def initialize(locale = 'US', secure = false)
-      host = HOSTS.fetch(locale) { raise BadLocale }
+      host = HOSTS.fetch(locale) { fail BadLocale }
       @aws_endpoint = "#{secure ? 'https' : 'http' }://#{host}/onca/xml"
     end
 
@@ -62,7 +62,7 @@ module Vacuum
     #
     # Returns self.
     def configure(credentials)
-      credentials.each { |key, val| self.send("#{key}=", val) }
+      credentials.each { |key, val| send("#{key}=", val) }
       self
     end
 
@@ -92,9 +92,9 @@ module Vacuum
     #
     # Returns a Vacuum Response.
     OPERATIONS.each do |operation|
-      method_name = operation.gsub(/(.)([A-Z])/,'\1_\2').downcase
+      method_name = operation.gsub(/(.)([A-Z])/, '\1_\2').downcase
       define_method(method_name) do |params, opts = {}|
-        params.has_key?(:query) ? opts = params : opts.update(query: params)
+        params.key?(:query) ? opts = params : opts.update(query: params)
         opts[:query].update('Operation' => operation)
 
         Response.new(get(opts))

data/lib/vacuum/response.rb

@@ -2,7 +2,22 @@ require 'delegate'
 require 'multi_xml'
 
 module Vacuum
+  # A wrapper around the Amazon Product Advertising API response.
   class Response < SimpleDelegator
+    class << self
+      attr_accessor :parser
+    end
+
+    def parser
+      @parser || self.class.parser
+    end
+
+    attr_writer :parser
+
+    def parse
+      parser ? parser.parse(body) : to_h
+    end
+
     def to_h
       MultiXml.parse(body)
     end

data/lib/vacuum/version.rb

@@ -1,3 +1,3 @@
 module Vacuum
-  VERSION = '1.1.1'
+  VERSION = '1.2.0'
 end

data/test/test_integration.rb

@@ -18,6 +18,7 @@ class TestIntegration < Minitest::Test
   include Vacuum
 
   def setup
+    skip if RUBY_VERSION < '2'
     VCR.insert_cassette('vacuum')
   end
 

data/test/test_vacuum.rb

@@ -22,23 +22,51 @@ class TestVacuum < Minitest::Test
   end
 
   def test_fetches_parsable_response
-    Excon.stub({}, { body: '<foo>bar</foo>' })
-    @req.configure(aws_access_key_id: 'key', aws_secret_access_key: 'secret', associate_tag: 'tag')
+    Excon.stub({}, body: '<foo/>')
     res = @req.item_lookup({}, mock: true)
-    refute_empty res.to_h
+    refute_empty res.parse
   end
 
   def test_alternative_query_syntax
-    Excon.stub({}, { body: '<foo>bar</foo>' })
-    req = Request.new
-    req.configure(aws_access_key_id: 'key', aws_secret_access_key: 'secret', associate_tag: 'tag')
-    res = req.item_lookup(query: {}, mock: true)
-    refute_empty res.to_h
+    Excon.stub({}, body: '<foo/>')
+    res = @req.item_lookup(query: {}, mock: true)
+    refute_empty res.parse
   end
 
   def test_force_encodes_body
     res = Object.new
-    def res.body; String.new.force_encoding('ASCII-8BIT'); end
+    def res.body
+      ''.force_encoding('ASCII-8BIT')
+    end
     assert_equal 'UTF-8', Response.new(res).body.encoding.name
   end
+
+  def test_sets_custom_parser_on_class_level
+    original_parser = Response.parser
+    Excon.stub({}, body: '<foo/>')
+    parser = MiniTest::Mock.new
+    parser.expect(:parse, '123', ['<foo/>'])
+    Response.parser = parser
+    res = @req.item_lookup(query: {}, mock: true)
+    assert_equal '123', res.parse
+    Response.parser = original_parser # clean up
+  end
+
+  def test_sets_custom_parser_on_instance_level
+    Excon.stub({}, body: '<foo/>')
+    res = @req.item_lookup(query: {}, mock: true)
+    parser = MiniTest::Mock.new
+    parser.expect(:parse, '123', ['<foo/>'])
+    res.parser = parser
+    assert_equal '123', res.parse
+  end
+
+  def test_casts_to_hash
+    Excon.stub({}, body: '<foo/>')
+    parser = MiniTest::Mock.new
+    res = @req.item_lookup(query: {}, mock: true)
+    assert_kind_of Hash, res.to_h
+    res.parser = parser
+    assert_kind_of Hash, res.to_h
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vacuum
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Hakan Ensari
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-04 00:00:00.000000000 Z
+date: 2014-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jeff
@@ -96,7 +96,7 @@ dependencies:
         version: '0'
 description: A wrapper to the Amazon Product Advertising API
 email:
-- hakan.ensari@papercavalier.com
+- me@hakanensari.com
 executables: []
 extensions: []
 extra_rdoc_files: []