sucker 1.0.0.beta.1 → 1.0.0.beta.2

data/README.markdown

@@ -1,9 +1,9 @@
 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 cURL and the Nokogiri implementation of the XML Mini module in Active Support. It is blazing fast and supports __the entire API__.
+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/540px-FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg)
+![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
 --------
@@ -15,11 +15,7 @@ Set up a worker.
       :key            => "API KEY",
       :secret         => "API SECRET")
 
-Optionally, fiddle with cURL. Say you want to query Amazon through a different network interface:
-
-    worker.curl { |c| c.interface = "eth0:0" }
-
-Set up a request.
+Prep a request.
 
     asin_batch = %w{
       0816614024 0143105825 0485113600 0816616779 0942299078
@@ -30,45 +26,44 @@ Set up a request.
       "ItemId"        => asin_batch,
       "ResponseGroup" => ["ItemAttributes", "OfferFull"] }
 
-Hit Amazon.
+Perform the request.
 
     response = worker.get
 
-View the internals of the response object.
-
-    p response.code,
-      response.time,
-      response.body,
-      response.xml
-
-Confirm response is valid.
+Debug.
 
-    response.valid?
+    if response.valid?
+      p response.code,
+        response.time,
+        response.body,
+        response.xml,
+        response.to_hash
+    end
 
-Cast response as a hash:
+Say you performed an item lookup. Iterate over all items and errors.
 
-    pp response.to_hash
+    response.node("Item").each { |item| ... }
+    response.node("Error").each { |error| ... }
 
-Grab a node:
-
-       response.node("Item"),
-       response.node("Error")
-
-Fetch another ASIN in a more DSL-y way.
+Perform a new request in a more DSL-y way.
 
     worker << { "ItemId"  => "0486454398" }
-    pp worker.get.node("Item")
+    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 and then dive into the [API docs](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html).
+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). [This](http://github.com/papercavalier/sucker/blob/master/spec/support/sucker.rb) is my RSpec helper.
+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 and 1.9.2.
+Specs pass against Ruby 1.8.7, Ruby 1.9.2, and Rubinius 1.1.

data/lib/sucker.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "active_support/xml_mini/nokogiri"
 require "curb"
 require "digest/md5"
@@ -7,10 +6,18 @@ require "sucker/response"
 require "uri"
 
 # = Sucker
+#
 # Sucker is a Ruby wrapper to the Amazon Product Advertising API.
 module Sucker
   CURRENT_AMAZON_API_VERSION = "2010-09-01"
 
+  # Initializes a request object
+  #
+  #   worker = Sucker.new(
+  #     :locale => "us",
+  #     :key    => "API KEY",
+  #     :secret => "API SECRET")
+  #
   def self.new(args={})
     Sucker::Request.new(args)
   end

data/lib/sucker/request.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 module Sucker #:nodoc
 
   # A wrapper around the API request
@@ -21,10 +20,17 @@ module Sucker #:nodoc
     # The hash of parameters to query Amazon with
     attr_accessor :parameters
 
+    # Initializes a request object
+    #
+    #   worker = Sucker.new(
+    #     :locale => "us",
+    #     :key    => "API KEY",
+    #     :secret => "API SECRET")
+    #
     def initialize(args)
       self.parameters = {
         "Service" => "AWSECommerceService",
-        "Version" => api_version
+        "Version" => CURRENT_AMAZON_API_VERSION
       }
 
       args.each { |k, v| send("#{k}=", v) }
@@ -35,22 +41,20 @@ module Sucker #:nodoc
       self.parameters.merge!(hash)
     end
 
-    # Gets Amazon API version.
-    def api_version
-      @api_version ||= CURRENT_AMAZON_API_VERSION
-    end
-
-    # Set Amazon API version.
-    def api_version=(version)
-      @api_version = version
-    end
-
-    # A helper method that sets the associate tag
+    # Sets the associate tag
+    #
+    #   worker = Sucker.new
+    #   worker.associate_tag = 'foo-bar'
+    #
     def associate_tag=(token)
       parameters["AssociateTag"] = token
     end
 
-    # A reusable, configurable cURL object
+    # A configurable curl object
+    #
+    #   worker = Sucker.new
+    #   worker.curl { |c| c.interface = "eth1" }
+    #
     def curl
       @curl ||= Curl::Easy.new
       yield @curl if block_given?
@@ -58,6 +62,10 @@ module Sucker #:nodoc
     end
 
     # Performs the request and returns a response object
+    #
+    #   worker = Sucker.new
+    #   response = worker.get
+    #
     def get
       curl.url = uri.to_s
       curl.perform
@@ -65,11 +73,24 @@ module Sucker #:nodoc
       Response.new(curl)
     end
 
-    # A helper method that sets the AWS Access Key ID
+    # Sets the AWS Access Key ID
+    #
+    #   worker = Sucker.new
+    #   worker.key = 'foo'
+    #
     def key=(token)
       parameters["AWSAccessKeyId"] = token
     end
 
+    # Sets Amazon API version.
+    #
+    #   worker = Sucker.new
+    #   worker.version = '"2010-06-01"'
+    #
+    def version=(version)
+      self.parameters["Version"] = version
+    end
+
     private
 
     # Timestamps parameters and concatenates them into a query string
@@ -83,19 +104,6 @@ module Sucker #:nodoc
         join("&")
     end
 
-    def escape(string)
-
-      # Shamelessly plagiarized from ruby_aaws, which in turn plagiarizes
-      # from the Ruby CGI library. All to please Amazon.
-      string.gsub( /([^a-zA-Z0-9_.~-]+)/ ) do
-        '%' + $1.unpack( 'H2' * $1.bytesize ).join( '%' ).upcase
-      end
-    end
-
-    def host
-      HOSTS[locale.to_sym]
-    end
-
     # Returns a signed and timestamped query string
     def build_signed_query
       query = build_query
@@ -107,6 +115,17 @@ module Sucker #:nodoc
       query + "&Signature=" + escape([hmac].pack("m").chomp)
     end
 
+    # Plagiarized from the Ruby CGI library via ruby_aaws
+    def escape(string)
+      string.gsub( /([^a-zA-Z0-9_.~-]+)/ ) do
+        '%' + $1.unpack( 'H2' * $1.bytesize ).join( '%' ).upcase
+      end
+    end
+
+    def host
+      HOSTS[locale.to_sym]
+    end
+
     def uri
       URI::HTTP.build(
         :host   => host,

data/lib/sucker/response.rb

@@ -1,9 +1,16 @@
-# encoding: utf-8
 module Sucker #:nodoc
 
   # A Nokogiri-driven wrapper around the cURL response
   class Response
-    attr_accessor :body, :code, :time
+
+    # The response body
+    attr_accessor :body
+
+    # The HTTP status code of the response
+    attr_accessor :code
+
+    # Transaction time in seconds for request
+    attr_accessor :time
 
     def initialize(curl)
       self.body = curl.body_str
@@ -12,27 +19,46 @@ module Sucker #:nodoc
     end
 
     # Queries an xpath and returns result as an array of hashes
+    #
+    # For instance, to get all items in an ItemLookup query:
+    #
+    #   response = worker.get
+    #   response.node("Item").each { |item| ... }
+    #
     def node(path)
       xml.xpath("//xmlns:#{path}").map { |node| strip_content(node.to_hash[path]) }
     end
 
     # Parses the response into a simple hash
+    #
+    #   response = worker.get
+    #   response.to_hash
+    #
     def to_hash
       strip_content(xml.to_hash)
     end
 
     # Checks if the HTTP response is OK
+    #
+    #    response = worker.get
+    #    p response.valid?
+    #    => true
+    #
     def valid?
       code == 200
     end
 
     # The XML document
+    #
+    #    response = worker.get
+    #    response.xml
     def xml
       @xml ||= Nokogiri::XML(body)
     end
 
     private
 
+    # Let's massage the somewhat-verbose XML Mini hash into better shape
     def strip_content(node)
       case node
       when Array 

data/lib/sucker/version.rb

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

data/spec/integration/errors_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker

data/spec/integration/images_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker

data/spec/integration/item_lookup_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker

data/spec/integration/item_search_spec.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 # http://github.com/papercavalier/sucker/issues#issue/2
 
 require "spec_helper"

data/spec/integration/multiple_locales_spec.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+require "spec_helper"
+
+module Sucker
+  describe "Multiple locales" do
+    use_vcr_cassette "integration/multiple_locales", :record => :new_episodes
+
+    it "threads multiple requests" do
+      locales = %w{us uk de ca fr jp}
+
+      params = {
+        "Operation"     => "ItemLookup",
+        "IdType"        => "ASIN",
+        "Condition"     => "All",
+        "MerchantId"    => "All",
+        "ResponseGroup" => "ItemAttributes",
+        "ItemId"        => "0816614024" }
+
+      threads = locales.map do |locale|
+        Thread.new do
+          worker = Sucker.new(
+            :locale => locale,
+            :key    => amazon["key"],
+            :secret => amazon["secret"])
+          worker << params
+          Thread.current[:response] = worker.get
+        end
+      end
+
+      bindings = []
+      threads.each do |thread|
+        thread.join
+        item = thread[:response].node("Item").first
+        bindings << item["ItemAttributes"]["Binding"]
+      end
+
+      bindings.uniq.should =~ %w{ Paperback Taschenbuch Broché ペーパーバック }
+    end
+  end
+end

data/spec/integration/related_items_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker

data/spec/integration/seller_listing_search_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker
@@ -13,7 +12,7 @@ module Sucker
 
       worker << {
         "Operation"   => "SellerListingSearch",
-        "SellerId"    => "A31N271NVIORU3" }
+        "SellerId"    => "A2JYSO6W6KEP83" }
 
       worker.get.node("SellerListings").first
     end

data/spec/integration/{twenty_items_in_one_request_spec.rb → twenty_items_spec.rb}

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker

data/spec/spec_helper.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "rubygems"
 require "bundler/setup"
 require "rspec"

data/spec/support/amazon_credentials.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 def amazon
   @amazon ||= YAML::load_file(File.dirname(__FILE__) + "/amazon.yml")
 end

data/spec/support/asins.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 def asins_fixture
   File.new(File.expand_path("../../fixtures/asins.txt", __FILE__), "r").map { |line| line.chomp }
 end

data/spec/support/vcr.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require 'vcr'
 
 VCR.config do |c|

data/spec/unit/sucker/request_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require "spec_helper"
 
 module Sucker
@@ -28,16 +27,10 @@ module Sucker
       end
     end
 
-    context "api_version" do
-      it "has a default value" do
-        worker.api_version.should_not be_nil
-      end
-    end
-
-    context "#api_version=" do
+    context "#version=" do
       it "sets the Amazon API version" do
-        worker.api_version = "foo"
-        worker.api_version.should eql "foo"
+        worker.version = "foo"
+        worker.parameters["Version"].should eql "foo"
       end
     end