vacuum 0.0.1 → 0.1.0

data/README.md

@@ -1,61 +1,43 @@
 # Vacuum
 
-Vacuum is a [Nokogiri][1]-backed Ruby wrapper to the [Amazon Product
-Advertising API] [2].
+[![travis] [2]] [3]
 
-[![travis](https://secure.travis-ci.org/hakanensari/vacuum.png)](http://travis-ci.org/hakanensari/vacuum)
+![vacuum] [1]
 
-## Installation
+Vacuum is a minimal Ruby wrapper to the [Amazon Product Advertising API] [4].
 
-Add to your Gemfile.
+# Usage
 
-    gem 'vacuum'
+```ruby
+require 'vacuum'
 
-## Usage
+# Create a request.
+req = Vacuum.new key:    'key',
+                 secret: 'secret',
+                 tag:    'tag',
+                 locale: 'us'
 
-Set up a request.
+# Build query.
+req.build 'Operation'   => 'ItemSearch',
+          'SearchIndex' => 'All',
+          'Keywords'    => 'Gilles Deleuze'
 
-    require "vacuum"
+# Execute.
+res = request.get
 
-    req = Vacuum["us"]
+# Consume response.
+if res.valid?
+  # res.to_hash
+  res.find('Item') do |item|
+    p item['ASIN']
+  end
+end
+```
 
-    req.configure do |c|
-      c.key    = AMAZON_KEY
-      c.secret = AMAZON_SECRET
-      c.tag    = AMAZON_ASSOCIATE_TAG
-    end
+Read further [here] [5].
 
-Search for something.
-
-    req << { :operation    => 'ItemSearch',
-             :search_index => 'All',
-             :keywords     => 'George Orwell' }
-    res = request.get
-
-Or use a shorthand.
-
-    res = req.search('George Orwell')
-
-Customise your request.
-
-    res = req.search('Books', :response_group => 'ItemAttributes',
-                              :power          => 'George Orwell'
-
-For a reference of available methods and syntax, [read here] [3].
-
-Consume the entire response.
-
-    res.to_hash
-
-Quickly drop down to a particular node.
-
-    res.each('Item') do |item|
-      puts item['ASIN']
-    end
-
-[Please see the project page] [4] for further detail.
-
-[1]: http://nokogiri.org/
-[2]: https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html
-[3]: https://github.com/hakanensari/vacuum/blob/master/lib/vacuum/operations.rb
-[4]: http://code.papercavalier.com/vacuum/
+[1]: https://github.com/hakanensari/vacuum/blob/master/vacuum.png?raw=true
+[2]: https://secure.travis-ci.org/hakanensari/vacuum.png
+[3]: http://travis-ci.org/hakanensari/vacuum
+[4]: https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html
+[5]: https://github.com/hakanensari/vacuum/blob/master/examples/

data/lib/vacuum/em.rb

@@ -0,0 +1,23 @@
+require 'vacuum'
+require 'em-http-request'
+
+module Vacuum
+  class Request
+    # Performs an async request.
+    #
+    # @yield Passes response to given block
+    def aget(&blk)
+      http = EM::HttpRequest.new(url).get
+      http.callback { blk.call _response(http) }
+      http.errback  { blk.call _response(http) }
+
+      nil
+    end
+
+    private
+
+    def _response(http)
+      Response.new(http.response, http.response_header.status)
+    end
+  end
+end

data/lib/vacuum/{builder.rb → hash_builder.rb}

@@ -1,15 +1,9 @@
 module Vacuum
-  module Builder
-    # Builds a hash from a Nokogiri XML document
+  module HashBuilder
+    # Builds a hash from a Nokogiri XML document.
     #
-    # @note In earlier versions of the library, I was relying on the
-    # XML Mini Nokogiri module in Active Support. This method
-    # essentially accomplishes the same.
-    #
-    # @see Based on https://gist.github.com/335286
-    #
-    # @param [Nokogiri::XML::Document] xml an XML document
-    # @return [Hash] a hashified version of the XML document
+    # @param [Nokogiri::XML::Document] xml An XML document
+    # @return [Hash]
     def self.from_xml(xml)
       case xml
       when Nokogiri::XML::Document
@@ -17,8 +11,8 @@ module Vacuum
       when Nokogiri::XML::Element
         hsh = {}
 
-        xml.attributes.each_pair do |key, attr|
-          hsh[key] = attr.value
+        xml.attributes.each_pair do |key, attribute|
+          hsh[key] = attribute.value
         end
 
         xml.children.each do |child|

data/lib/vacuum/request.rb

@@ -1,131 +1,119 @@
 module Vacuum
-  # A wrapper around the request to the Amazon Product Advertising API
+  # A wrapper around the request to the Amazon Product Advertising API.
   class Request
-    include CartOperations
-    include LookupOperations
-    include SearchOperations
-
-    # The latest Amazon API version
-    #
-    # @see http://aws.amazon.com/archives/Product%20Advertising%20API
-    #
-    # @note If you have a whitelisted access key, override this in your
-    # parameters with an earlier version.
+    # The latest Amazon API version.
     CURRENT_API_VERSION = '2011-08-01'
 
-    # Creates a new request for specified locale
+    # A list of Amazon endpoints.
+    HOSTS = {
+      :ca => 'ecs.amazonaws.ca',
+      :cn => 'webservices.amazon.cn',
+      :de => 'ecs.amazonaws.de',
+      :es => 'webservices.amazon.es',
+      :fr => 'ecs.amazonaws.fr',
+      :it => 'webservices.amazon.it',
+      :jp => 'ecs.amazonaws.jp',
+      :uk => 'ecs.amazonaws.co.uk',
+      :us => 'ecs.amazonaws.com'
+    }
+
+    # Creates a new request for given locale and credentials.
     #
-    # @param [#to_sym] locale two-letter abbreviation for locale
-    def initialize(locale)
-      @locale = Locale.new(locale.to_sym)
-      @params = Hash.new
+    # @param [Hash] options
+    # @option opts [#to_sym] :locale An Amazon locale
+    # @option opts [String] :key An Amazon AWS access key ID
+    # @option opts [String] :secret An Amazon AWS access secret key
+    # @option opts [String] :tag An Amazon Associate tag
+    # @raise [MissingKey] An Amazon AWS access key ID was not given
+    # @raise [MissingSecret] An Amazon AWS secret key was not given
+    # @raise [MissingTag] An Amazon Associate tag was not given
+    # @return [self]
+    def initialize(options)
+      _reset!
+
+      locale  = (options[:locale] || :us).to_sym
+      @host   = HOSTS[locale]    or raise BadLocale
+      @key    = options[:key]    or raise MissingKey
+      @secret = options[:secret] or raise MissingSecret
+      @tag    = options[:tag]    or raise MissingTag
     end
 
-    # Merges a hash of request parameters into the query
-    #
-    # @param [Hash] hsh pairs of parameter keys and values
+    # Merges given parameters into the request query.
     #
-    # @example
-    #   request << { :key => 'value' }
-    #
-    def <<(hsh)
+    # @param [Hash] hsh Pairs of keys and values
+    # @return [self]
+    def build(hsh)
       hsh.each do |k, v|
-        # Cast value to string.
-        v = v.is_a?(Array) ? v.join(',') : v.to_s
-
-        # Remove whitespace after commas.
-        v.gsub!(/,\s+/, ',')
-
-        # Camelize key.
-        k = k.to_s.
-              split('_').
-              map { |w| w[0, 1] = w[0, 1].upcase; w }.
-              join
-
-        @params[k] = v
+        @params[k] = v.is_a?(Array) ? v.join(',') : v.to_s
       end
+
+      self
     end
 
-    # Configures the Amazon locale
-    #
-    # @yield passes locale to block for configuration
+    # Replaces the request query with given parameters.
     #
-    # @example
-    #   request.configure do |c|
-    #     c.key    = YOUR_KEY
-    #     c.secret = YOUR_SECRET
-    #     c.tag    = YOUR_ASSOCIATE_TAG
-    #   end
-    #
-    def configure(&block)
-      block.call(@locale)
+    # see(#build)
+    def build!(hsh = {})
+      _reset!
+      build hsh
     end
 
-    # Performs a request
+    # Performs a request.
     #
-    # @return [Vacuum::Response] a response
+    # @return [Vacuum::Response] A response
     def get
-      resp = Net::HTTP.get_response(url)
-
-      Response.new(resp.body, resp.code)
+      res = Net::HTTP.get_response(url)
+      Response.new(res.body, res.code)
     end
 
-    # @return [Hash] params The request parameters
-    # @raise [Vacuum::MissingKey] Amazon key is missing
-    # @raise [Vacuum::MissingTag] Amazon associate tag is
-    # missing
+    # @return [Hash] The parameters that make up the request query.
     def params
-      raise MissingKey unless @locale.key
-      raise MissingTag unless @locale.tag
-
-      { 'AWSAccessKeyId' => @locale.key,
-        'AssociateTag'   => @locale.tag,
-        'Service'        => 'AWSECommerceService',
-        'Timestamp'      => timestamp,
-        'Version'        => CURRENT_API_VERSION }.merge(@params)
-    end
-
-    # Resets the request parameters
-    def reset!
-      @params = {}
+      _default_params.merge(@params)
     end
 
-    # @raise [Vacuum::MissingSecret] Amazon secret is missing
-    # @return [URI::HTTP] the Amazon URL
+    # @return [URI::HTTP] The URL for the API request
     def url
-      raise MissingSecret unless @locale.secret
-
-      URI::HTTP.build(:host  => @locale.host,
+      URI::HTTP.build :host  => @host,
                       :path  => '/onca/xml',
-                      :query => sign(query))
+                      :query => _query_string
     end
 
     private
 
-    def escape(value)
+    def _default_params
+      default = {
+        'AWSAccessKeyId' => @key,
+        'AssociateTag'   => @tag,
+        'Service'        => 'AWSECommerceService',
+        'Timestamp'      => _timestamp,
+        'Version'        => CURRENT_API_VERSION
+      }
+    end
+
+    def _escape(value)
       value.gsub(/([^a-zA-Z0-9_.~-]+)/) do
         '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
       end
     end
 
-    def query
-      params.sort.map { |k, v| "#{k}=" + escape(v) }.join('&')
-    end
+    def _query_string
+      qs   = params.sort.map { |k, v| "#{k}=" + _escape(v) }.join('&')
 
-    def sign(unsigned_query)
-      digest = OpenSSL::Digest::Digest.new('sha256')
-      url_string = ['GET',
-                    @locale.host,
-                    '/onca/xml',
-                    unsigned_query].join("\n")
-      hmac = OpenSSL::HMAC.digest(digest, @locale.secret, url_string)
-      signature = escape([hmac].pack('m').chomp)
+      # Sign query string.
+      dig  = OpenSSL::Digest::Digest.new 'sha256'
+      req  = ['GET', @host, '/onca/xml', qs]
+      hmac = OpenSSL::HMAC.digest dig, @secret, req.join("\n")
+      sig  = _escape [hmac].pack('m').chomp
 
-      "#{unsigned_query}&Signature=#{signature}"
+      "#{qs}&Signature=#{sig}"
+    end
+
+    def _reset!
+      @params = {}
     end
 
-    def timestamp
-      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+    def _timestamp
+      Time.now.utc.iso8601
     end
   end
 end

data/lib/vacuum/response.rb

@@ -1,85 +1,63 @@
 module Vacuum
-  # A wrapper around the API response
+  # A wrapper around the API response.
   class Response
 
-    # @return [String] body the response body
+    # @return [String] body The response body
     attr_accessor :body
 
-    # @return [Integer] code the HTTP status code of the response
+    # @return [Integer] code The HTTP status code of the response
     attr_accessor :code
 
-    # Creates a new response
+    # Creates a new response.
     #
-    # @param [String] body the response body
-    # @param [#to_i] code the HTTP status code of the response
+    # @param [String] body The response body
+    # @param [#to_i] code The HTTP status code of the response
     def initialize(body, code)
       @body = body
       @code = code.to_i
     end
 
-    # Queries for a specified attribute and yields to a given block
-    # each matching document
-    #
-    # @param [String] query attribute to be queried
-    # @yield passes matching nodes to given block
-    #
-    # @example
-    #   resp.each('Item') { |item| p item }
-    #
-    def each(query, &block)
-      find(query).each { |match| block.call(match) }
-    end
-
-    # @return [Array] errors in the response
+    # @return [Array] Errors in the response
     def errors
-      find('Error')
+      find 'Error'
     end
 
-    # Queries for a specified attribute and returns matching nodes
+    # Queries for a given attribute, yielding matching nodes to a block if
+    # given one.
     #
-    # @param [String] query attribute to be queried
-    # @return [Array] matching nodes
+    # @param [String] Query attribute to be queried
+    # @yield Optionally passes matching nodes to a given block
+    # @return [Array] Matches
     #
     # @example
-    #   items = resp.find('Item')
+    #   items = res.find('Item')
+    #   asins = res.find('Item') { |item| item['ASIN'] }
     #
     def find(query)
-      xml.xpath("//xmlns:#{query}").map { |e| Builder.from_xml(e) }
+      xml.xpath("//xmlns:#{query}").map do |node|
+        hsh = HashBuilder.from_xml node
+        block_given? ? yield(hsh) : hsh
+      end
     end
-    alias [] find
 
-    # @return [true, false] checks if the response has errors
+    # @return [true, false] Whether the response has errors
     def has_errors?
       errors.count > 0
     end
 
-    # Queries for a specifed attribute, yields to a given block
-    # matching nodes, and collects final values.
-    #
-    # @param [String] query attribute to be queried
-    # @yield passes matching nodes to given block
-    # @return [Array] processed results
-    #
-    # @example
-    #   asins = resp.map('Item') { |item| item['ASIN'] }
-    #
-    def map(path, &block)
-      find(path).map { |match| block.call(match) }
-    end
-
-    # @return [Hash] a hashified version of the response body
+    # @return [Hash] A hash representation of the entire response.
     def to_hash
-      Builder.from_xml(xml)
+      HashBuilder.from_xml xml
     end
 
-    # @return [true, false] checks if the HTTP response is OK
+    # @return [true, false] Whether the HTTP response is OK
     def valid?
       code == 200
     end
 
     # @return [Nokogiri::XML] the XML document
     def xml
-      @xml ||= Nokogiri::XML(@body)
+      @xml ||= Nokogiri::XML @body
     end
   end
 end

data/lib/vacuum/version.rb

@@ -1,3 +1,3 @@
 module Vacuum
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/lib/vacuum.rb

@@ -1,23 +1,24 @@
+require 'forwardable'
 require 'net/http'
 require 'nokogiri'
 require 'openssl'
+require 'time'
 
-%w{cart_operations lookup_operations search_operations builder cart
-   error locale request response}.each do |f|
+%w{hash_builder request response}.each do |f|
   require "vacuum/#{f}"
 end
 
-# Vacuum is a Ruby wrapper to the Amazon Product Advertising
-# API.
+
+# Vacuum is a Ruby wrapper to the Amazon Product Advertising API.
 module Vacuum
-  @requests = Hash.new
+  class BadLocale     < ArgumentError; end
+  class MissingKey    < ArgumentError; end
+  class MissingSecret < ArgumentError; end
+  class MissingTag    < ArgumentError; end
+
+  class << self
+    extend Forwardable
 
-  # @param [#to_sym] locale a locale key
-  # @return [Vacuum::Request] a request
-  #
-  # @note The locale key may be any of the following: +ca+, +cn+, +de+,
-  # +es+, +fr+, +it+, +jp+, +uk+, or +us+.
-  def self.[](locale)
-    @requests[locale] ||= Request.new(locale)
+    def_delegators Request, :new
   end
 end

data/spec/vacuum/{builder_spec.rb → hash_builder_spec.rb}

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 module Vacuum
-  describe Builder do
+  describe HashBuilder do
     let(:xml) do
       xml = <<-XML.gsub!(/>\s+</, '><').strip!
       <?xml version=\"1.0\" ?>
@@ -17,19 +17,19 @@ module Vacuum
 
     describe '.from_xml' do
       it 'returns a hash' do
-        Builder.from_xml(xml).should be_an_instance_of Hash
+        HashBuilder.from_xml(xml).should be_an_instance_of Hash
       end
 
       it 'handles only childs' do
-        Builder.from_xml(xml)['Title'].should eql 'Anti-Oedipus'
+        HashBuilder.from_xml(xml)['Title'].should eql 'Anti-Oedipus'
       end
 
       it 'handles arrays' do
-        Builder.from_xml(xml)['Author'].should be_a Array
+        HashBuilder.from_xml(xml)['Author'].should be_a Array
       end
 
       it 'handles attributes' do
-        node = Builder.from_xml(xml)['Creator']
+        node = HashBuilder.from_xml(xml)['Creator']
         node['Role'].should eql 'Translator'
         node['__content__'].should eql 'Robert Hurley'
       end