sucker 1.0.0.beta.2 → 1.0.0.beta.3

data/History.md

@@ -0,0 +1,14 @@
+Version 1.0.0.beta3
+========
+
+Release date: 2010-10-25
+
+Added
+-----
+
+* #find yields to a block if given one
+
+Deprecated
+----------
+
+* Renamed #node to #find

data/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
  
-Copyright (c) 2009 Paper Cavalier
+Copyright (c) 2010 Paper Cavalier
  
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+Sucker
+======
+
+Sucker is a Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html). It runs on [curb](http://github.com/taf2/curb) and [the Nokogiri implementation of the XML Mini module](http://github.com/rails/rails/blob/master/activesupport/lib/active_support/xml_mini/nokogiri.rb) in Active Support. It's fast and supports __the entire API__.
+
+![Sucker](http://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg/480px-FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg)
+
+Examples
+--------
+
+Set up a worker.
+
+    worker = Sucker.new(
+      :locale => "us",
+      :key    => "API KEY",
+      :secret => "API SECRET")
+
+Prepare a request.
+
+    asin_batch = %w{
+      0816614024 0143105825 0485113600 0816616779 0942299078
+      0816614008 144006654X 0486400360 0486417670 087220474X }
+    worker << {
+      "Operation"     => "ItemLookup",
+      "IdType"        => "ASIN",
+      "ItemId"        => asin_batch,
+      "ResponseGroup" => ["ItemAttributes", "OfferFull"] }
+
+Perform the request.
+
+    response = worker.get
+
+Debug.
+
+    p response.valid?,
+      response.code,
+      response.time,
+      response.body,
+      response.xml,
+      response.to_hash
+
+Iterate over items in your item lookup.
+
+    response.find("Item")  { |item| ... }
+
+Iterate over errors.
+
+    response.find("Error") { |error| ... }
+
+Repeat ad infinitum.
+
+Check my [integration specs](http://github.com/papercavalier/sucker/tree/master/spec/integration/) for more examples. See [twenty items](http://github.com/papercavalier/sucker/tree/master/spec/integration/twenty_items_spec.rb) and [multiple locales](http://github.com/papercavalier/sucker/tree/master/spec/integration/multiple_locales_spec.rb) for relatively advanced usage.
+
+Last but not least, dive into the [API docs](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html) to construct your own queries.
+
+Stubbing
+--------
+
+Use [VCR](http://github.com/myronmarston/vcr) to stub your requests.
+
+Caveat: Match URIs on host only and create a new cassette for each stubbed query. [This is how I do it](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb).
+
+Compatibility
+-------------
+
+Specs pass against Ruby 1.8.7, Ruby 1.9.2, and Rubinius 1.1.

data/lib/sucker/request.rb

@@ -37,6 +37,14 @@ module Sucker #:nodoc
     end
 
     # A helper method that merges a hash into existing parameters
+    #
+    #   worker = Sucker.new
+    #   worker << {
+    #     "Operation"     => "ItemLookup",
+    #     "IdType"        => "ASIN",
+    #     "ItemId"        => "0816614024",
+    #     "ResponseGroup" => "ItemAttributes" }
+    #
     def <<(hash)
       self.parameters.merge!(hash)
     end
@@ -82,10 +90,10 @@ module Sucker #:nodoc
       parameters["AWSAccessKeyId"] = token
     end
 
-    # Sets Amazon API version.
+    # Sets the Amazon API version
     #
     #   worker = Sucker.new
-    #   worker.version = '"2010-06-01"'
+    #   worker.version = '2010-06-01'
     #
     def version=(version)
       self.parameters["Version"] = version

data/lib/sucker/response.rb

@@ -18,15 +18,22 @@ module Sucker #:nodoc
       self.time = curl.total_time
     end
 
-    # Queries an xpath and returns result as an array of hashes
+    # Queries an xpath and returns an array of matching nodes
     #
-    # For instance, to get all items in an ItemLookup query:
+    # Will yield each match if a block is given
     #
     #   response = worker.get
-    #   response.node("Item").each { |item| ... }
+    #   response.find("Item") { |item| ... }
     #
-    def node(path)
-      xml.xpath("//xmlns:#{path}").map { |node| strip_content(node.to_hash[path]) }
+    def find(path)
+      node = xml.xpath("//xmlns:#{path}").map { |node| strip_content(node.to_hash[path]) }
+      node.each { |e| yield e } if block_given?
+      node
+    end
+
+    def node(path) # :nodoc:
+      warn "[DEPRECATION] `node` is deprecated.  Use `find` instead."
+      find(path)
     end
 
     # Parses the response into a simple hash
@@ -58,7 +65,7 @@ module Sucker #:nodoc
 
     private
 
-    # Let's massage the somewhat-verbose XML Mini hash into better shape
+    # Let's massage that hash
     def strip_content(node)
       case node
       when Array 

data/lib/sucker/version.rb

@@ -1,3 +1,3 @@
 module Sucker #:nodoc
-  VERSION = "1.0.0.beta.2"
+  VERSION = "1.0.0.beta.3"
 end

data/spec/integration/alternate_versions_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+module Sucker
+  describe "Alternate versions" do
+    use_vcr_cassette "integration/alternate_versions", :record => :new_episodes
+
+    let(:worker) do
+      worker = Sucker.new(
+        :locale => "uk",
+        :key    => amazon["key"],
+        :secret => amazon["secret"])
+      worker << {
+        "Operation"     => "ItemLookup",
+        "IdType"        => "ASIN",
+        "ResponseGroup" => "AlternateVersions",
+        "ItemId"        => "0141044012" }
+      worker
+    end
+
+    it "returns alternate versions" do
+      response = worker.get
+      alternate_versions = response.find("AlternateVersion")
+      alternate_versions.should be_an_instance_of Array
+      alternate_versions.first.should have_key "ASIN"
+    end
+  end
+end

data/spec/integration/errors_spec.rb

@@ -23,13 +23,13 @@ module Sucker
     end
 
     it "returns two errors" do
-      errors = response.node("Error")
+      errors = response.find("Error")
       errors.size.should eql 2
       errors.first["Message"].should include "not a valid value"
     end
 
     it "returns one item" do
-      items = response.node("ItemAttributes")
+      items = response.find("ItemAttributes")
       items.size.should eql 1
     end
   end

data/spec/integration/france_spec.rb

@@ -18,7 +18,7 @@ module Sucker
         "MerchantId"    => "All",
         "ResponseGroup" => ["ItemAttributes", "OfferFull"],
         "ItemId"        => "2070119874" }
-      worker.get.node("Item").first
+      worker.get.find("Item").first
     end
 
     it "returns an item" do

data/spec/integration/images_spec.rb

@@ -15,7 +15,7 @@ module Sucker
         "IdType"        => "ASIN",
         "ResponseGroup" => "Images",
         "ItemId"        => "0816614024" }
-      worker.get.node("Item").first
+      worker.get.find("Item").first
     end
 
     it "has an ASIN" do

data/spec/integration/item_lookup_spec.rb

@@ -25,7 +25,7 @@ module Sucker
         worker.get
       end
 
-      let(:item) { response.node("Item").first }
+      let(:item) { response.find("Item").first }
 
       it "returns an item" do
         item.should be_an_instance_of Hash
@@ -41,8 +41,8 @@ module Sucker
       end
 
       it "returns no errors" do
-        response.node("Error").should be_empty
-        response.node("Error").should be_an_instance_of Array
+        response.find("Error").should be_empty
+        response.find("Error").should be_an_instance_of Array
       end
     end
 
@@ -51,7 +51,7 @@ module Sucker
 
       let(:items) do
         worker << { "ItemId" => ["0816614024", "0143105825"] }
-        worker.get.node("Item")
+        worker.get.find("Item")
       end
 
       it "returns two items" do

data/spec/integration/item_search_spec.rb

@@ -31,7 +31,7 @@ module Sucker
 
       response = worker.get
       response.should be_valid
-      response.node("TotalPages").first.should be_an_instance_of String
+      response.find("TotalPages").first.should be_an_instance_of String
     end
   end
 end

data/spec/integration/japan_spec.rb

@@ -16,7 +16,7 @@ module Sucker
         "IdType"        => "ASIN",
         "ResponseGroup" => ["ItemAttributes", "OfferFull"],
         "ItemId"        => "482224816X" }
-      worker.get.node("Item").first
+      worker.get.find("Item").first
     end
 
     it "returns an array of items" do

data/spec/integration/keyword_search_spec.rb

@@ -0,0 +1,28 @@
+require "spec_helper"
+
+module Sucker
+  describe "Keyword Search" do
+    use_vcr_cassette "integration/keyword_search", :record => :new_episodes
+
+    let(:worker) do
+      worker = Sucker.new(
+        :locale => "us",
+        :key    => amazon["key"],
+        :secret => amazon["secret"])
+      worker << {
+        "Operation"   => "ItemSearch",
+        "SearchIndex" => "Books",
+        "Keywords"    => "zizek lacan",
+        "Sort"        => "relevancerank" } # also try salesrank and reviewrank
+      worker
+    end
+
+    it "returns matches" do
+      items  = worker.get.find("Item")
+      items.size.should > 0
+      items.each do |item|
+        item["ItemAttributes"]["Title"].should_not be_nil
+      end
+    end
+  end
+end

data/spec/integration/multiple_locales_spec.rb

@@ -11,8 +11,6 @@ module Sucker
       params = {
         "Operation"     => "ItemLookup",
         "IdType"        => "ASIN",
-        "Condition"     => "All",
-        "MerchantId"    => "All",
         "ResponseGroup" => "ItemAttributes",
         "ItemId"        => "0816614024" }
 
@@ -27,11 +25,10 @@ module Sucker
         end
       end
 
-      bindings = []
-      threads.each do |thread|
+      bindings = threads.map do |thread|
         thread.join
-        item = thread[:response].node("Item").first
-        bindings << item["ItemAttributes"]["Binding"]
+        item = thread[:response].find("Item").first
+        item["ItemAttributes"]["Binding"]
       end
 
       bindings.uniq.should =~ %w{ Paperback Taschenbuch Broché ペーパーバック }

data/spec/integration/power_search_spec.rb

@@ -0,0 +1,36 @@
+require "spec_helper"
+
+# http://docs.amazonwebservices.com/AWSECommerceService/2010-09-01/DG/index.html?PowerSearchSyntax.html
+#
+# author: ambrose and binding: (abridged or large print) and pubdate: after 11-1996
+# subject: history and (Spain or Mexico) and not military and language: Spanish
+# (subject: marketing and author: kotler) or (publisher: harper and subject: "high technology")
+# keywords: "high tech*" and not fiction and pubdate: during 1999
+# isbn: 0446394319 or 0306806819 or 1567993850
+
+module Sucker
+  describe "Power search" do
+    use_vcr_cassette "integration/power_search", :record => :new_episodes
+
+    let(:worker) do
+      worker = Sucker.new(
+        :locale => "us",
+        :key    => amazon["key"],
+        :secret => amazon["secret"])
+      worker << {
+        "Operation"   => "ItemSearch",
+        "SearchIndex" => "Books",
+        "Power"       => "author:lacan or deleuze and not fiction",
+        "Sort"        => "relevancerank" }
+      worker
+    end
+
+    it "returns matches" do
+      items  = worker.get.find("Item")
+      items.size.should > 0
+      items.each do |item|
+        item["ItemAttributes"]["Title"].should_not be_nil
+      end
+    end
+  end
+end

data/spec/integration/related_items_spec.rb

@@ -23,8 +23,8 @@ module Sucker
       it "finds parent and related items" do
         worker << { "ItemId" => "0415246334" }
         response = worker.get
-        response.node("RelatedItem").size.should eql 1
-        parent_asin = response.node("RelatedItem").first["Item"]["ASIN"]
+        response.find("RelatedItem").size.should eql 1
+        parent_asin = response.find("RelatedItem").first["Item"]["ASIN"]
       end
     end
 
@@ -34,7 +34,7 @@ module Sucker
       it "finds related items" do
         worker << { "ItemId" => "B000ASPUES" }
         response = worker.get
-        response.node("RelatedItem").size.should > 1
+        response.find("RelatedItem").size.should > 1
       end
     end
   end

data/spec/integration/seller_listing_search_spec.rb

@@ -14,7 +14,7 @@ module Sucker
         "Operation"   => "SellerListingSearch",
         "SellerId"    => "A2JYSO6W6KEP83" }
 
-      worker.get.node("SellerListings").first
+      worker.get.find("SellerListings").first
     end
 
     it "returns page count" do

data/spec/integration/twenty_items_spec.rb

@@ -31,7 +31,7 @@ module Sucker
         "ItemLookup.1.ItemId" => asins[0, 10],
         "ItemLookup.2.ItemId" => asins[10, 10] }
 
-      worker.get.node("Item")
+      worker.get.find("Item")
     end
 
     it "returns 20 items" do

data/spec/unit/sucker/response_spec.rb

@@ -40,16 +40,25 @@ module Sucker
       end
     end
 
-    context "#node" do
-      it "returns a collection of hashified nodes" do
-        node = response.node("ItemAttributes")
+    context "#find" do
+      it "returns an array of matching nodes" do
+        node = response.find("ItemAttributes")
         node.map { |book| book["ISBN"] }.should eql asins
       end
 
       it "returns an empty array if there are no matches" do
-        node = response.node("Foo")
+        node = response.find("Foo")
         node.should eql []
       end
+
+      it "yields to a block if given one" do
+        has_yielded = false
+        response.find("ItemAttributes") do |item|
+          has_yielded = true
+          item.should be_an_instance_of Hash
+        end
+        has_yielded.should be_true
+      end
     end
 
     context "#to_hash" do

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: sucker
 version: !ruby/object:Gem::Version 
-  hash: 62196359
+  hash: 62196357
   prerelease: true
   segments: 
   - 1
   - 0
   - 0
   - beta
-  - 2
-  version: 1.0.0.beta.2
+  - 3
+  version: 1.0.0.beta.3
 platform: ruby
 authors: 
 - Hakan Ensari
@@ -18,7 +18,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-22 00:00:00 +01:00
+date: 2010-10-25 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -196,15 +196,19 @@ files:
 - lib/sucker/version.rb
 - lib/sucker.rb
 - LICENSE
-- README.markdown
+- README.md
+- History.md
 - spec/fixtures/asins.txt
+- spec/integration/alternate_versions_spec.rb
 - spec/integration/errors_spec.rb
 - spec/integration/france_spec.rb
 - spec/integration/images_spec.rb
 - spec/integration/item_lookup_spec.rb
 - spec/integration/item_search_spec.rb
 - spec/integration/japan_spec.rb
+- spec/integration/keyword_search_spec.rb
 - spec/integration/multiple_locales_spec.rb
+- spec/integration/power_search_spec.rb
 - spec/integration/related_items_spec.rb
 - spec/integration/seller_listing_search_spec.rb
 - spec/integration/twenty_items_spec.rb
@@ -254,13 +258,16 @@ specification_version: 3
 summary: A Ruby wrapper to the Amazon Product Advertising API
 test_files: 
 - spec/fixtures/asins.txt
+- spec/integration/alternate_versions_spec.rb
 - spec/integration/errors_spec.rb
 - spec/integration/france_spec.rb
 - spec/integration/images_spec.rb
 - spec/integration/item_lookup_spec.rb
 - spec/integration/item_search_spec.rb
 - spec/integration/japan_spec.rb
+- spec/integration/keyword_search_spec.rb
 - spec/integration/multiple_locales_spec.rb
+- spec/integration/power_search_spec.rb
 - spec/integration/related_items_spec.rb
 - spec/integration/seller_listing_search_spec.rb
 - spec/integration/twenty_items_spec.rb

data/README.markdown

@@ -1,69 +0,0 @@
-Sucker
-======
-
-Sucker is a Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html). It runs on [curb](http://github.com/taf2/curb) and the Nokogiri implementation of the XML Mini module in Active Support. It is blazing fast and supports __the entire API__.
-
-![Sucker](http://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg/480px-FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg)
-
-Examples
---------
-
-Set up a worker.
-
-    worker = Sucker.new(
-      :locale         => "us",
-      :key            => "API KEY",
-      :secret         => "API SECRET")
-
-Prep a request.
-
-    asin_batch = %w{
-      0816614024 0143105825 0485113600 0816616779 0942299078
-      0816614008 144006654X 0486400360 0486417670 087220474X }
-    worker << {
-      "Operation"     => "ItemLookup",
-      "IdType"        => "ASIN",
-      "ItemId"        => asin_batch,
-      "ResponseGroup" => ["ItemAttributes", "OfferFull"] }
-
-Perform the request.
-
-    response = worker.get
-
-Debug.
-
-    if response.valid?
-      p response.code,
-        response.time,
-        response.body,
-        response.xml,
-        response.to_hash
-    end
-
-Say you performed an item lookup. Iterate over all items and errors.
-
-    response.node("Item").each { |item| ... }
-    response.node("Error").each { |error| ... }
-
-Perform a new request in a more DSL-y way.
-
-    worker << { "ItemId"  => "0486454398" }
-    worker.get.node("Item").each { |item| ... }
-
-Repeat ad infinitum.
-
-Check the [integration specs](http://github.com/papercavalier/sucker/tree/master/spec/integration/) for more examples. In particullar, see [twenty items](http://github.com/papercavalier/sucker/tree/master/spec/integration/twenty_items_spec.rb) and [multiple locales](http://github.com/papercavalier/sucker/tree/master/spec/integration/multiple_locales_spec.rb) for advanced usage.
-
-Finally, dive into the [API docs](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html) to construct your own queries.
-
-Stubbing
---------
-
-Use [VCR](http://github.com/myronmarston/vcr) to stub your requests. [This file](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb) should help you set up VCR with RSpec.
-
-Don't match requests on URI. The parameters include a timestamp that results in each URI being unique.
-
-Compatibility
--------------
-
-Specs pass against Ruby 1.8.7, Ruby 1.9.2, and Rubinius 1.1.