sucker 1.1.4 → 1.2.0

data/README.md

@@ -1,21 +1,23 @@
 Sucker
 ======
 
-Sucker is a minimal 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 is a [cURL-](http://github.com/taf2/curb) and [Nokogiri-](http://github.com/rails/rails/blob/master/activesupport/lib/active_support/xml_mini/nokogiri.rb)driven Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html).
+
+It's fast and supports __the entire API__.
 
 ![Electrolux](https://github.com/papercavalier/sucker/raw/master/electrolux.jpg)
 
 Usage
 -----
 
-Set up a worker.
+Where's your worker?
 
     worker = Sucker.new(
-      :locale => "us",
+      :locale => :us,
       :key    => "API KEY",
       :secret => "API SECRET")
 
-Prepare a request.
+Build a query.
 
     worker << {
       "Operation"     => "ItemLookup",
@@ -27,19 +29,15 @@ Get a response.
 
     response = worker.get
 
-Make sure nothing went [awry](http://gloss.papercavalier.com/2010/11/01/amazon-call-throttling-demystified.html).
-
-    response.valid?
-
-Now parse it.
+Parse.
 
-    items = response.map("Item") do |item|
-      # parse item
+    books = response.map("Item") do |item|
+      # parse
     end
 
 Repeat ad infinitum.
 
-[Check my integration specs](http://github.com/papercavalier/sucker/tree/master/spec/integration/) for more detailed 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.
+[Check the features](http://relishapp.com/papercavalier/sucker) for more detailed examples.
 
 Read the source code and dive into the [Amazon API docs](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html).
 
@@ -48,18 +46,14 @@ Stubbing
 
 Use [VCR](http://github.com/myronmarston/vcr) to stub your requests.
 
-Match URIs on host only and create a new cassette for each query. [This is how my VCR setup looks like](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb).
+[This is how my VCR setup looks like](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb).
 
 Compatibility
 -------------
 
-Specs pass against Ruby 1.8.7 and Ruby 1.9.2.
-
-Sucker works seamlessly with or without Rails.
-
-Sucker won't work on JRuby. (We got Curl under the hood. It's worth the trade-off.)
+Specs pass against Ruby 1.8.7 and Ruby 1.9.2. Sucker has cURL under the hood, so no JRuby.
 
 Afterword
 ---------
 
-No DSL. No object mapping. Pure Nokogiri goodness.
+Don't overabstract a spaghetti API.

data/lib/sucker.rb

@@ -1,16 +1,16 @@
-require "sucker/request"
-require "sucker/response"
+require 'sucker/parameters'
+require 'sucker/request'
+require 'sucker/response'
 
 # = Sucker
 #
 # Sucker is a Ruby wrapper to the Amazon Product Advertising API.
 module Sucker
-  CURRENT_AMAZON_API_VERSION = "2010-10-01"
 
   # Initializes a request object
   #
   #   worker = Sucker.new(
-  #     :locale => "us",
+  #     :locale => :us,
   #     :key    => "API KEY",
   #     :secret => "API SECRET")
   #

data/lib/sucker/parameters.rb

@@ -0,0 +1,28 @@
+require 'active_support/inflector'
+
+module Sucker
+  class Parameters < Hash
+    API_VERSION = '2010-11-01'
+    SERVICE     = 'AWSECommerceService'
+
+    def initialize #:nodoc
+      self.store 'Service',   SERVICE
+      self.store 'Version',   API_VERSION
+      self.store 'Timestamp', timestamp
+    end
+
+    def normalize
+      inject({}) do |h, kv|
+        k, v = kv
+        h[k.to_s.camelize] = v.is_a?(Array) ? v.join(',') : v.to_s
+        h
+      end
+    end
+
+    private
+
+    def timestamp
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+    end
+  end
+end

data/lib/sucker/request.rb

@@ -1,7 +1,7 @@
-require "curb"
-require "openssl"
-require "ostruct"
-require "uri"
+require 'curb'
+require 'openssl'
+require 'ostruct'
+require 'uri'
 
 module Sucker #:nodoc:
 
@@ -16,39 +16,25 @@ module Sucker #:nodoc:
       :jp  => 'ecs.amazonaws.jp' }
     PATH = "/onca/xml"
 
-    # The Amazon locale to query
-    attr_accessor :locale
-
     # The Amazon secret access key
     attr_accessor :secret
 
-    # 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" => CURRENT_AMAZON_API_VERSION
-      }
-
       args.each { |k, v| send("#{k}=", v) }
     end
 
-    # Merges a hash into existing parameters
+    # Merges a hash into the existing parameters
     #
-    #   worker = Sucker.new
     #   worker << {
-    #     "Operation"     => "ItemLookup",
-    #     "IdType"        => "ASIN",
-    #     "ItemId"        => "0816614024",
-    #     "ResponseGroup" => "ItemAttributes" }
+    #     "Operation" => "ItemLookup",
+    #     "IdType"    => "ASIN",
+    #     "ItemId"    => "0816614024" }
     #
     def <<(hash)
       self.parameters.merge!(hash)
@@ -56,12 +42,11 @@ module Sucker #:nodoc:
 
     # Returns the associate tag for the current locale
     def associate_tag
-      associate_tags[locale.to_sym] rescue nil
+      @associate_tags[locale.to_sym] rescue ''
     end
 
     # Sets the associate tag for the current locale
     #
-    #   worker = Sucker.new
     #   worker.associate_tag = 'foo-bar'
     #
     def associate_tag=(token)
@@ -80,10 +65,8 @@ module Sucker #:nodoc:
     #    tags = {
     #      :us => 'foo-bar-10',
     #      :uk => 'foo-bar-20',
-    #      :de => 'foo-bar-30',
     #      ... }
     #
-    #    worker = Sucker.new
     #    worker.associate_tags = tags
     #
     def associate_tags=(tokens)
@@ -92,7 +75,6 @@ module Sucker #:nodoc:
 
     # Returns options for curl and yields them if given a block
     #
-    #   worker = Sucker.new
     #   worker.curl_opts { |c| c.interface = "eth1" }
     #
     def curl_opts
@@ -104,61 +86,56 @@ module Sucker #:nodoc:
 
     # Performs a request and returns a response
     #
-    #   worker = Sucker.new
     #   response = worker.get
     #
-    def get
-      raise ArgumentError.new "Locale missing"         unless locale
-      raise ArgumentError.new "AWS access key missing" unless key
-
-      curl = Curl::Easy.perform(uri.to_s) do |easy|
-        curl_opts.each { |k, v| easy.send("#{k}=", v) }
-      end
-
-      Response.new(curl)
-    end
-
-    # Performs a request for all locales, returns an array of responses, and yields
-    # them if given a block
-    #
-    #    worker = Sucker.new
+    # Optionally, pass one or more locales to query specific locales or `:all`
+    # to query all locales.
     #
-    #    # This blocks until all requests are complete
-    #    responses = worker.get_all
+    #   responses = worker.get(:us)
     #
-    #    # This does not block
-    #    worker.get_all do |response|
-    #      process_response
-    #    end
+    #   responses = worker.get(:all)
     #
-    def get_all
-      uris = HOSTS.keys.map do |locale|
-        self.locale = locale
-        uri.to_s
-      end
-      responses = []
+    def get(*args)
+      case args.count
 
-      Curl::Multi.get(uris, curl_opts) do |curl|
-        response = Response.new(curl)
-        yield response if block_given?
-        responses << response
+      when 0
+        curl = Curl::Easy.perform(uri.to_s) do |easy|
+          curl_opts.each { |k, v| easy.send("#{k}=", v) }
+        end
+        Response.new(curl)
+
+      when 1
+        arg = args.first
+        if arg == :all
+          get_multi locales
+        else
+          self.locale = arg
+          get
+        end
+
+      else
+        get_multi args
       end
+    end
 
-      responses
+    def get_all # :nodoc:
+      warn "[DEPRECATION] `get_all` is deprecated. Please use `get(:all) instead."
+      get(:all)
     end
 
     # Returns the AWS access key for the current locale
     def key
-      @keys[locale.to_sym]
+      raise ArgumentError.new "AWS access key missing" unless @keys[locale]
+
+      @keys[locale]
     end
 
-    # Sets a global AWS access key ID
+    # Sets a global AWS access key
     #
-    #   worker = Sucker.new
     #   worker.key = 'foo'
     #
     def key=(token)
-      @keys = HOSTS.keys.inject({}) do |keys, locale|
+      @keys = locales.inject({}) do |keys, locale|
         keys[locale] = token
         keys
       end
@@ -170,63 +147,95 @@ module Sucker #:nodoc:
     # and Canada and (2) the UK, France, and Germany count against the same call
     # rate quota.
     #
-    #    #   keys = {
+    #   keys = {
     #     :us => 'foo',
     #     :uk => 'bar',
-    #     :de => 'baz',
     #     ... }
     #
-    #   worker = Sucker.new
     #   worker.keys = keys
     #
     def keys=(tokens)
       @keys = tokens
     end
 
+    def locale
+      raise ArgumentError.new "Locale not set" unless @locale
+
+      @locale
+    end
+
+    # Sets the current Amazon locale
+    #
+    # Valid values are :us, :uk, :de, :ca, :fr, and :jp.
+    def locale=(new_locale)
+      new_locale = new_locale.to_sym
+
+      raise ArgumentError.new "Invalid locale" unless locales.include? new_locale
+
+      @locale = new_locale
+    end
+
+    # The parameters to query Amazon with
+    def parameters
+      @parameters ||= Parameters.new
+    end
+
     # Sets the Amazon API version
     #
-    #   worker = Sucker.new
     #   worker.version = '2010-06-01'
     #
     def version=(version)
-      self.parameters["Version"] = version
+      self.parameters['Version'] = version
     end
 
     private
 
-    # Timestamps parameters and concatenates them into a query string
     def build_query
       parameters.
-        merge(timestamp).
-        merge({ "AWSAccessKeyId" => key }).
-        merge({ "AssociateTag"   => associate_tag }).
+        normalize.
+        merge({ 'AWSAccessKeyId' => key }).
+        merge({ 'AssociateTag'   => associate_tag }).
         sort.
-        collect do |k, v|
-          "#{k}=" + escape(v.is_a?(Array) ? v.join(",") : v.to_s)
-        end.
-        join("&")
+        map do |k, v|
+          "#{k}=" + escape(v)
+        end.join('&')
     end
 
-    # Returns a signed and timestamped query string
     def build_signed_query
       query = build_query
 
-      digest = OpenSSL::Digest::Digest.new("sha256")
-      string = ["GET", host, PATH, query].join("\n")
+      digest = OpenSSL::Digest::Digest.new('sha256')
+      string = ['GET', host, PATH, query].join("\n")
       hmac = OpenSSL::HMAC.digest(digest, secret, string)
+      signature = escape([hmac].pack('m').chomp)
+
+      query + '&Signature=' + signature
+    end
 
-      query + "&Signature=" + escape([hmac].pack("m").chomp)
+    def escape(value)
+      value.gsub(/([^a-zA-Z0-9_.~-]+)/) do
+        '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
+      end
     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
+    def get_multi(locales)
+      responses = []
+
+      Curl::Multi.get(uris, curl_opts) do |curl|
+        response = Response.new(curl)
+        yield response if block_given?
+        responses << response
       end
+
+      responses
     end
 
     def host
-      HOSTS[locale.to_sym]
+      HOSTS[locale]
+    end
+
+    def locales
+      @locales ||= HOSTS.keys
     end
 
     def uri
@@ -236,8 +245,11 @@ module Sucker #:nodoc:
         :query  => build_signed_query)
     end
 
-    def timestamp
-      { "Timestamp" => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ') }
+    def uris
+      locales.map do |locale|
+        self.locale = locale
+        uri.to_s
+      end
     end
   end
 end

data/lib/sucker/response.rb

@@ -32,6 +32,11 @@ module Sucker #:nodoc:
       find(path).each { |e| yield e }
     end
 
+    # Returns an array of errors in the reponse
+    def errors
+      find("Error")
+    end
+
     # Queries an xpath and returns an array of matching nodes
     #
     #   response = worker.get
@@ -41,6 +46,11 @@ module Sucker #:nodoc:
       xml.xpath("//xmlns:#{path}").map { |e| strip_content(e.to_hash[path]) }
     end
 
+    # Returns true if response contains errors
+    def has_errors?
+      errors.count > 0
+    end
+
     # A shorthand that yields matches to a block and collects returned values
     #
     #   descriptions = worker.get.map("Item") { |item| build_description(item) }