vacuum 0.0.1

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2010 Hakan Ensari
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+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.

data/README.md

@@ -0,0 +1,61 @@
+# Vacuum
+
+Vacuum is a [Nokogiri][1]-backed Ruby wrapper to the [Amazon Product
+Advertising API] [2].
+
+[![travis](https://secure.travis-ci.org/hakanensari/vacuum.png)](http://travis-ci.org/hakanensari/vacuum)
+
+## Installation
+
+Add to your Gemfile.
+
+    gem 'vacuum'
+
+## Usage
+
+Set up a request.
+
+    require "vacuum"
+
+    req = Vacuum["us"]
+
+    req.configure do |c|
+      c.key    = AMAZON_KEY
+      c.secret = AMAZON_SECRET
+      c.tag    = AMAZON_ASSOCIATE_TAG
+    end
+
+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/

data/lib/vacuum.rb

@@ -0,0 +1,23 @@
+require 'net/http'
+require 'nokogiri'
+require 'openssl'
+
+%w{cart_operations lookup_operations search_operations builder cart
+   error locale request response}.each do |f|
+  require "vacuum/#{f}"
+end
+
+# Vacuum is a Ruby wrapper to the Amazon Product Advertising
+# API.
+module Vacuum
+  @requests = Hash.new
+
+  # @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)
+  end
+end

data/lib/vacuum/builder.rb

@@ -0,0 +1,51 @@
+module Vacuum
+  module Builder
+    # 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
+    def self.from_xml(xml)
+      case xml
+      when Nokogiri::XML::Document
+        from_xml(xml.root)
+      when Nokogiri::XML::Element
+        hsh = {}
+
+        xml.attributes.each_pair do |key, attr|
+          hsh[key] = attr.value
+        end
+
+        xml.children.each do |child|
+          result = from_xml(child)
+
+          if child.name == 'text'
+            if hsh.empty?
+              return result
+            else
+              hsh['__content__'] = result
+            end
+          elsif hsh[child.name]
+            case hsh[child.name]
+            when Array
+              hsh[child.name] << result
+            else
+              hsh[child.name] = [hsh[child.name]] << result
+            end
+          else
+            hsh[child.name] = result
+          end
+        end
+
+        hsh
+      else
+        xml.content.to_s
+      end
+    end
+  end
+end

data/lib/vacuum/cart.rb

@@ -0,0 +1,90 @@
+module Vacuum
+  class Cart
+    # @return [String] cart_id
+    attr :id
+
+    # @return [String] hmac
+    attr :hmac
+
+    attr :items
+
+    # @return [Vacuum::Response] last_response last response
+    # returned by the Amazon API
+    attr :last_response
+
+    # @return [String] purchase_url
+    attr :purchase_url
+
+    attr :sub_total
+
+    # Creates a new cart
+    #
+    # @param [Vacuum::Request] req an API request
+    # @param [Hash] params a hash of parameters
+    def initialize(req, params)
+      @req = req
+      get 'Create', params
+    end
+
+    # Clears the cart
+    #
+    # @param [Hash] params a hash of parameters
+    def clear(params = {})
+      get 'Clear', params
+    end
+
+    private
+
+    def get(operation, params)
+      @req.reset!
+
+      if id
+        @req << { 'CartId'    => id,
+                  'HMAC'      => hmac }
+      end
+
+      @req << { 'Operation' => "Cart#{operation}" }.merge(params)
+
+      @last_response = @req.get
+      @items         = @last_response.find('CartItems')
+      @id            = @last_response.find('CartId').first
+      @hmac          = @last_response.find('HMAC').first
+      @purchase_url  = @last_response.find('PurchaseURL').first
+      @sub_total     = @last_response.find('SubTotal').first
+    end
+
+    # Add items to cart
+    #
+    # @param [String] cart_id
+    # @param [String] hmac
+    # @param [Hash] params
+    # @return [Vacuum::Cart] a response
+    # def add_to_cart(cart_id, hmac, params)
+    #   cartify 'Add', { 'CartId' => cart_id,
+    #                    'HMAC'   => hmac }.merge(params)
+    # end
+
+
+    # Gets an existing cart
+    #
+    # @param [String] cart_id
+    # @param [String] hmac
+    # @param [Hash] params
+    # @return [Vacuum::Cart] a response
+    # def get_cart(cart_id, hmac, params)
+    #   cartify 'Get', { 'CartId' => cart_id,
+    #                    'HMAC'   => hmac }.merge(params)
+    # end
+
+    # Modifies an existing cart
+    #
+    # @param [String] cart_id
+    # @param [String] hmac
+    # @param [Hash] params
+    # @return [Vacuum::Cart] a response
+    # def modify_cart(cart_id, hmac, params)
+    #   cartify 'Modify', { 'CartId' => cart_id,
+    #                       'HMAC'   => hmac }.merge(params)
+    # end
+  end
+end

data/lib/vacuum/cart_operations.rb

@@ -0,0 +1,12 @@
+module Vacuum
+  # Cart operations
+  module CartOperations
+    # Creates a cart
+    #
+    # @param [Hash] params
+    # @return [Vacuum::Cart] a cart
+    def create_cart(params)
+      Cart.new(self, params)
+    end
+  end
+end

data/lib/vacuum/error.rb

@@ -0,0 +1,13 @@
+module Vacuum
+  # Raised when a bad locale is specified
+  class BadLocale < ArgumentError; end
+
+  # Raised when the Amazon key is not specified
+  class MissingKey < ArgumentError; end
+
+  # Raised when the Amazon secret is not specified
+  class MissingSecret < ArgumentError; end
+
+  # Raised when the Amazon associate tag is not specified
+  class MissingTag < ArgumentError; end
+end

data/lib/vacuum/locale.rb

@@ -0,0 +1,39 @@
+module Vacuum
+  # An Amazon locale
+  class Locale
+    # Amazon hosts
+    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',
+              :us => 'ecs.amazonaws.com',
+              :uk => 'ecs.amazonaws.co.uk' }
+
+    # Country codes for Amazon locales
+    LOCALES = HOSTS.keys
+
+    # @return [String] the Amazon Web Services access key
+    attr_accessor :key
+
+    # @return [String] the Amazon Web Services secret
+    attr_accessor :secret
+
+    # @return [String] the Amazon associate tag
+    attr_accessor :tag
+
+    # @param [Symbol] locale the locale key
+    # @raise [Vacuum::BadLocale] locale is bad
+    def initialize(locale)
+      raise BadLocale unless LOCALES.include?(locale)
+      @locale = locale
+    end
+
+    # @return [String] the Amazon host
+    def host
+      HOSTS[@locale]
+    end
+  end
+end

data/lib/vacuum/lookup_operations.rb

@@ -0,0 +1,62 @@
+module Vacuum
+  # Lookup operations
+  module LookupOperations
+    # Given up to ten item ids, returns some or all of the item
+    # attributes, depending on the response group specified in the
+    # request.
+    #
+    # @param [Array] item_ids splat of item IDs and an optional hash of
+    # parameters
+    # @return [Vacuum::Response] a response
+    #
+    # Id Type defaults to ASIN.
+    #
+    # @example The following returns some basic information for the
+    # ASIN 0679753354.
+    #
+    #   req.find('0679753354')
+    #
+    # @example The following request returns cover art for the same
+    # ASIN.
+    #
+    #   req.find('0679753354', :response_group => 'Images')
+    #
+    def find(*item_ids)
+      reset!
+      params = item_ids.last.is_a?(Hash) ? item_ids.pop : {}
+      self.<<({ 'Operation' => 'ItemLookup',
+                'ItemId'    => item_ids }.merge(params))
+
+      get
+    end
+
+    # Given a browse node ID, returns the specified browse node’s name,
+    # children, and ancestors.
+    #
+    # @param [String] browse_node_id browse node ID
+    # @params [Hash] params hash of parameters
+    # @return [Vacuum::Response] a response
+    def find_browse_node(browse_node_id, params = {})
+      reset!
+      self.<<({ 'Operation'    => 'BrowseNodeLookup',
+                'BrowseNodeId' => browse_node_id }.merge(params))
+
+      get
+    end
+
+    # Given up to ten item ids, returns up to ten products per page
+    # that are similar to those items
+    #
+    # @param [Array] item_ids splat of item IDs and an optional hash of
+    # parameters
+    # @return [Vacuum::Response] a response
+    def find_similar(*item_ids)
+      reset!
+      params = item_ids.last.is_a?(Hash) ? item_ids.pop : {}
+      self.<<({ 'Operation' => 'SimilarityLookup',
+                'ItemId'    => item_ids }.merge(params))
+
+      get
+    end
+  end
+end

data/lib/vacuum/request.rb

@@ -0,0 +1,131 @@
+module Vacuum
+  # 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.
+    CURRENT_API_VERSION = '2011-08-01'
+
+    # Creates a new request for specified locale
+    #
+    # @param [#to_sym] locale two-letter abbreviation for locale
+    def initialize(locale)
+      @locale = Locale.new(locale.to_sym)
+      @params = Hash.new
+    end
+
+    # Merges a hash of request parameters into the query
+    #
+    # @param [Hash] hsh pairs of parameter keys and values
+    #
+    # @example
+    #   request << { :key => 'value' }
+    #
+    def <<(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
+      end
+    end
+
+    # Configures the Amazon locale
+    #
+    # @yield passes locale to block for configuration
+    #
+    # @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)
+    end
+
+    # Performs a request
+    #
+    # @return [Vacuum::Response] a response
+    def get
+      resp = Net::HTTP.get_response(url)
+
+      Response.new(resp.body, resp.code)
+    end
+
+    # @return [Hash] params The request parameters
+    # @raise [Vacuum::MissingKey] Amazon key is missing
+    # @raise [Vacuum::MissingTag] Amazon associate tag is
+    # missing
+    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 = {}
+    end
+
+    # @raise [Vacuum::MissingSecret] Amazon secret is missing
+    # @return [URI::HTTP] the Amazon URL
+    def url
+      raise MissingSecret unless @locale.secret
+
+      URI::HTTP.build(:host  => @locale.host,
+                      :path  => '/onca/xml',
+                      :query => sign(query))
+    end
+
+    private
+
+    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 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)
+
+      "#{unsigned_query}&Signature=#{signature}"
+    end
+
+    def timestamp
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+    end
+  end
+end

data/lib/vacuum/response.rb

@@ -0,0 +1,85 @@
+module Vacuum
+  # A wrapper around the API response
+  class Response
+
+    # @return [String] body the response body
+    attr_accessor :body
+
+    # @return [Integer] code the HTTP status code of the response
+    attr_accessor :code
+
+    # Creates a new 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
+    def errors
+      find('Error')
+    end
+
+    # Queries for a specified attribute and returns matching nodes
+    #
+    # @param [String] query attribute to be queried
+    # @return [Array] matching nodes
+    #
+    # @example
+    #   items = resp.find('Item')
+    #
+    def find(query)
+      xml.xpath("//xmlns:#{query}").map { |e| Builder.from_xml(e) }
+    end
+    alias [] find
+
+    # @return [true, false] checks if 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
+    def to_hash
+      Builder.from_xml(xml)
+    end
+
+    # @return [true, false] checks if the HTTP response is OK
+    def valid?
+      code == 200
+    end
+
+    # @return [Nokogiri::XML] the XML document
+    def xml
+      @xml ||= Nokogiri::XML(@body)
+    end
+  end
+end

data/lib/vacuum/search_operations.rb

@@ -0,0 +1,43 @@
+module Vacuum
+  # Search operations
+  module SearchOperations
+    # Returns up to ten items that satisfy the search criteria,
+    # including one or more search indices.
+    #
+    # @param [String, nil] search_index search index or keyword query
+    # @param [String, Hash] params keyword query or hash of parameters
+    # @return [Vacuum::Response] a reponse
+    #
+    # @example The following searches the entire Amazon catalog for the
+    # keyword 'book'.
+    #
+    #   req.search('book')
+    #
+    # @example The following searches the books search index for the
+    # keyword 'lacan'.
+    #
+    #   req.search('Books', 'lacan')
+    #
+    # @example The following runs a power search on the books search
+    # index for non-fiction titles authored by Lacan and sorts results
+    # by Amazon's relevance ranking.
+    #
+    #   req.search('Books', :power => 'author:lacan and not fiction',
+    #                           :sort  => 'relevancerank')
+    #
+    def search(search_index, params = nil)
+      reset!
+      if params.nil?
+        params = { 'Keywords' => search_index }
+        search_index  = 'All'
+      end
+      if params.is_a? String
+        params = { 'Keywords' => params }
+      end
+      self.<<({ 'Operation'   => 'ItemSearch',
+                'SearchIndex' => search_index }.merge(params))
+
+      get
+    end
+  end
+end

data/lib/vacuum/version.rb

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

data/spec/fixtures/http_response

@@ -0,0 +1 @@
+<?xml version="1.0" ?><ItemLookupResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2011-08-01"><OperationRequest><RequestId>86b89a15-b717-4d95-99aa-fe531b4ca762</RequestId><Arguments><Argument Name="Operation" Value="ItemLookup"></Argument><Argument Name="Service" Value="AWSECommerceService"></Argument><Argument Name="AssociateTag" Value="theorydot08-20"></Argument><Argument Name="Version" Value="2011-08-01"></Argument><Argument Name="Signature" Value="vOT9O1NW8PYLvrUX6KI3jrZ4Fg7LdtEYTrlsWzhbm1k="></Argument><Argument Name="ItemId" Value="0816614024,0143105825"></Argument><Argument Name="IdType" Value="ASIN"></Argument><Argument Name="AWSAccessKeyId" Value="0ZVSQ33MDFPQS8H2PM02"></Argument><Argument Name="Timestamp" Value="2011-07-29T17:52:34Z"></Argument></Arguments><RequestProcessingTime>0.0111990000000000</RequestProcessingTime></OperationRequest><Items><Request><IsValid>True</IsValid><ItemLookupRequest><IdType>ASIN</IdType><ItemId>0816614024</ItemId><ItemId>0143105825</ItemId><ResponseGroup>Small</ResponseGroup><VariationPage>All</VariationPage></ItemLookupRequest></Request><Item><ASIN>0816614024</ASIN><DetailPageURL>http://www.amazon.com/Thousand-Plateaus-Schizophrenia-Gilles-Deleuze/dp/0816614024%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D165953%26creativeASIN%3D0816614024</DetailPageURL><ItemLinks><ItemLink><Description>Technical Details</Description><URL>http://www.amazon.com/Thousand-Plateaus-Schizophrenia-Gilles-Deleuze/dp/tech-data/0816614024%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>Add To Baby Registry</Description><URL>http://www.amazon.com/gp/registry/baby/add-item.html%3Fasin.0%3D0816614024%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>Add To Wedding Registry</Description><URL>http://www.amazon.com/gp/registry/wedding/add-item.html%3Fasin.0%3D0816614024%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>Add To Wishlist</Description><URL>http://www.amazon.com/gp/registry/wishlist/add-item.html%3Fasin.0%3D0816614024%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>Tell A Friend</Description><URL>http://www.amazon.com/gp/pdp/taf/0816614024%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>All Customer Reviews</Description><URL>http://www.amazon.com/review/product/0816614024%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink><ItemLink><Description>All Offers</Description><URL>http://www.amazon.com/gp/offer-listing/0816614024%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0816614024</URL></ItemLink></ItemLinks><ItemAttributes><Author>Gilles Deleuze</Author><Creator Role="Contributor">Felix Guattari</Creator><Manufacturer>Univ Of Minnesota Press</Manufacturer><ProductGroup>Book</ProductGroup><Title>Thousand Plateaus: Capitalism and Schizophrenia</Title></ItemAttributes></Item><Item><ASIN>0143105825</ASIN><DetailPageURL>http://www.amazon.com/Anti-Oedipus-Capitalism-Schizophrenia-Penguin-Classics/dp/0143105825%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D165953%26creativeASIN%3D0143105825</DetailPageURL><ItemLinks><ItemLink><Description>Technical Details</Description><URL>http://www.amazon.com/Anti-Oedipus-Capitalism-Schizophrenia-Penguin-Classics/dp/tech-data/0143105825%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>Add To Baby Registry</Description><URL>http://www.amazon.com/gp/registry/baby/add-item.html%3Fasin.0%3D0143105825%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>Add To Wedding Registry</Description><URL>http://www.amazon.com/gp/registry/wedding/add-item.html%3Fasin.0%3D0143105825%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>Add To Wishlist</Description><URL>http://www.amazon.com/gp/registry/wishlist/add-item.html%3Fasin.0%3D0143105825%26SubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>Tell A Friend</Description><URL>http://www.amazon.com/gp/pdp/taf/0143105825%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>All Customer Reviews</Description><URL>http://www.amazon.com/review/product/0143105825%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink><ItemLink><Description>All Offers</Description><URL>http://www.amazon.com/gp/offer-listing/0143105825%3FSubscriptionId%3D0ZVSQ33MDFPQS8H2PM02%26tag%3Dtheorydot08-20%26linkCode%3Dxm2%26camp%3D2025%26creative%3D386001%26creativeASIN%3D0143105825</URL></ItemLink></ItemLinks><ItemAttributes><Author>Gilles Deleuze</Author><Author>Felix Guattari</Author><Creator Role="Translator">Robert Hurley</Creator><Creator Role="Translator">Mark Seem</Creator><Creator Role="Introduction">Mark Seem</Creator><Creator Role="Translator">Helen Lane</Creator><Creator Role="Preface">Michel Foucault</Creator><Manufacturer>Penguin Classics</Manufacturer><ProductGroup>Book</ProductGroup><Title>Anti-Oedipus: Capitalism and Schizophrenia (Penguin Classics)</Title></ItemAttributes></Item></Items></ItemLookupResponse>

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec'
+
+begin
+  require 'pry'
+rescue LoadError
+end
+
+require File.expand_path('../../lib/vacuum', __FILE__)
+
+RSpec.configure do |c|
+  c.treat_symbols_as_metadata_keys_with_true_values = true
+end

data/spec/vacuum/builder_spec.rb

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

data/spec/vacuum/lookup_operations_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+module Vacuum
+  describe LookupOperations do
+    let(:req) { Request.new('us') }
+
+    before do
+      req.configure do |c|
+        c.key = 'foo'
+        c.tag = 'bar'
+      end
+      req.stub!(:get)
+    end
+
+    describe "#find" do
+      before do
+        req.find('1', '2', :foo => 'bar')
+      end
+
+      it 'merges item ids' do
+        req.params['ItemId'].should eql '1,2'
+      end
+
+      it 'merges additional parameters' do
+        req.params['Foo'].should eql 'bar'
+      end
+    end
+
+    describe "#find_browse_node" do
+      before do
+        req.find_browse_node('123', :foo => 'bar')
+      end
+
+      it 'merges item ids' do
+        req.params['BrowseNodeId'].should eql '123'
+      end
+
+      it 'merges additional parameters' do
+        req.params['Foo'].should eql 'bar'
+      end
+    end
+
+    describe "#find_similar" do
+      before do
+        req.find_similar('1', '2')
+      end
+
+      it 'merges item ids' do
+        req.params['ItemId'].should eql '1,2'
+      end
+    end
+  end
+end

data/spec/vacuum/request_spec.rb

@@ -0,0 +1,183 @@
+require 'spec_helper'
+
+module Vacuum
+  describe Request do
+    let(:req) { Request.new('us') }
+
+    describe '#<<' do
+      before do
+        req.configure do |c|
+          c.key = 'foo'
+          c.tag = 'bar'
+        end
+
+        req.reset!
+      end
+
+      it 'merges parameters into the query' do
+        req << { 'Key' => 'value' }
+
+        req.params['Key'].should eql 'value'
+      end
+
+      it 'camelizes keys' do
+        req << { :some_key => 'value' }
+
+        req.params.should have_key 'SomeKey'
+      end
+
+      it 'leaves camelized keys as is' do
+        req << { 'SomeKey' => 'value' }
+
+        req.params.should have_key 'SomeKey'
+      end
+
+      it 'casts numeric values to string' do
+        req << { 'Key' => 1 }
+
+        req.params['Key'].should eql '1'
+      end
+
+      it 'converts array values to string' do
+        req << { 'Key' => ['foo', 'bar'] }
+
+        req.params['Key'].should eql 'foo,bar'
+      end
+
+      it 'removes whitespace after commas in values' do
+        req << { 'Key' => 'foo,  bar' }
+
+        req.params['Key'].should eql 'foo,bar'
+      end
+    end
+
+    describe '#configure' do
+      it 'yields the locale' do
+        req.configure(&:class).should eql Locale
+      end
+    end
+
+    describe '#get' do
+      before do
+        req.configure do |c|
+          c.key    = 'foo'
+          c.secret = 'bar'
+          c.tag    = 'baz'
+        end
+      end
+
+      it 'returns a response' do
+        req.get.should be_a Response
+      end
+
+      it 'raises an error if secret is missing' do
+        req.configure { |c| c.secret = nil }
+
+        expect { req.get }.to raise_error MissingSecret
+      end
+    end
+
+    describe '#params' do
+      before do
+        req.configure do |c|
+          c.key = 'foo'
+          c.tag = 'bar'
+        end
+      end
+
+      it 'raises an error if key is missing' do
+        req.configure { |c| c.key = nil }
+
+        expect { req.params }.to raise_error MissingKey
+      end
+
+      it 'raises an error if tag is missing' do
+        req.configure { |c| c.tag = nil }
+
+        expect { req.params }.to raise_error MissingTag
+      end
+
+      it 'includes common request parameters' do
+        req.params['Service'].should eql 'AWSECommerceService'
+      end
+
+      it 'includes credentials' do
+        req.params.should have_key 'AWSAccessKeyId'
+        req.params.should have_key 'AssociateTag'
+      end
+
+      it 'includes a timestamp' do
+        req.params['Timestamp'].should =~ /^\d+-\d+-\d+T\d+:\d+:\d+Z$/
+      end
+
+      context 'when no API version is specified' do
+        it 'includes the current API version' do
+          req.params['Version'].should eql Request::CURRENT_API_VERSION
+        end
+      end
+
+      context 'when an API version is specified' do
+        it 'includes the specified API version' do
+          req << { 'Version' => '1' }
+          req.params['Version'].should eql '1' 
+        end
+      end
+    end
+
+    describe '#reset!' do
+      before do
+        req.configure do |c|
+          c.key = 'foo'
+          c.tag = 'bar'
+        end
+      end
+
+      it 'resets the request parameters' do
+        req << { 'Key' => 'value' }
+        req.params.should have_key 'Key'
+
+        req.reset!
+        req.params.should_not have_key 'Key'
+      end
+    end
+
+    describe '#url' do
+      before do
+        req.configure do |c|
+          c.key = 'foo'
+          c.secret = 'bar'
+          c.tag = 'baz'
+        end
+      end
+
+      it 'builds a URL' do
+        req.url.should be_a URI::HTTP
+      end
+
+      it 'canonicalizes the request parameters' do
+        req.url.query.should match /\w+=\w+&/
+      end
+
+      it 'sorts the request parameters' do
+        req << { 'A' => 1 }
+        req.url.query.should match /^A=1&/
+      end
+
+      it 'URL-encodes values' do
+        req << { :key => 'foo,bar' }
+        req.url.query.should match /foo%2Cbar/
+      end
+
+      it 'signs the query' do
+        req.url.query.should match /&Signature=/
+      end
+
+      it 'raises an error if no secret is specified' do
+        expect do
+          req.configure { |c| c.secret = nil }
+          req.url
+        end.to raise_error MissingSecret
+      end
+    end
+  end
+end

data/spec/vacuum/response_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+module Vacuum
+  describe Response do
+    let(:resp) do
+      body = File.read(File.expand_path('../../fixtures/http_response', __FILE__))
+      code = '200'
+      Response.new(body, code)
+    end
+
+    describe '#each' do
+      it 'yields matches to given block' do
+        yielded = false
+        resp.each('Item') do |item|
+          yielded = true
+        end
+
+        yielded.should be_true
+      end
+    end
+
+    describe '#errors' do
+      it 'returns an array of errors' do
+        resp.body =  <<-EOF.gsub!(/>\s+</, '><').strip!
+        <?xml version=\"1.0\" ?>
+        <resp xmlns="http://example.com">
+          <Errors>
+            <Error>foo</Error>
+          </Errors>
+        </resp>
+        EOF
+
+        resp.errors.should =~ ['foo']
+      end
+    end
+
+    describe '#has_errors?' do
+      context 'when a resp does not contain any errors' do
+        it 'returns false' do
+          resp.stub!(:errors).and_return([])
+
+          resp.should_not have_errors
+        end
+      end
+
+      context 'when a resp contains errors' do
+        it 'returns true' do
+          resp.stub!(:errors).and_return([1])
+
+          resp.should have_errors
+        end
+      end
+    end
+
+    describe '#find' do
+      it 'returns an array of matching nodes' do
+        resp.find('ASIN').should_not be_empty
+      end
+    end
+
+    describe "#map" do
+      it "yields each match to a block and maps returned values" do
+        titles = resp.map('Item') { |i| i['ItemAttributes']['Title'] }
+
+        titles.count.should eql 2
+      end
+    end
+
+    describe '#to_hash' do
+      it 'casts resp to a hash' do
+        resp.to_hash.should be_a Hash
+      end
+    end
+
+    describe '#valid?' do
+      context 'when HTTP status is OK' do
+        it 'returns true' do
+          resp.should be_valid
+        end
+      end
+
+      context 'when HTTP status is not OK' do
+        it 'returns false' do
+          resp.code = 403
+          resp.should_not be_valid
+        end
+      end
+    end
+
+    describe '#xml' do
+      it 'returns a Nokogiri document' do
+        resp.xml.should be_an_instance_of Nokogiri::XML::Document
+      end
+    end
+  end
+end

data/spec/vacuum/search_operations_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+module Vacuum
+  describe SearchOperations do
+    let(:req) { Request.new('us') }
+
+    before do
+      req.configure do |c|
+        c.key = 'foo'
+        c.tag = 'bar'
+      end
+      req.stub!(:get)
+    end
+
+    describe "#search" do
+      context "when given a keyword" do
+        before do
+          req.search('foo')
+        end
+
+        it "does a keyword search" do
+          req.params['Keywords'].should eql 'foo'
+        end
+
+        it "searches all products" do
+          req.params["SearchIndex"].should eql 'All'
+        end
+      end
+
+      context "when given a search index and a keyword" do
+        before do
+          req.search('foo', 'bar')
+        end
+
+        it "does a keyword search" do
+          req.params['Keywords'].should eql 'bar'
+        end
+
+        it "sets the search index" do
+          req.params["SearchIndex"].should eql 'foo'
+        end
+      end
+
+      context "when given a search index and parameters" do
+        before do
+          req.search('foo', :bar => 'baz')
+        end
+
+        it "sets the parameters" do
+          req.params['Bar'].should eql 'baz'
+        end
+
+        it "sets the search index" do
+          req.params["SearchIndex"].should eql 'foo'
+        end
+      end      
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: vacuum
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Hakan Ensari
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &70206980398600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70206980398600
+description: Vacuum is a Ruby wrapper to the Amazon Product Advertising API.
+email:
+- code@papercavalier.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/vacuum/builder.rb
+- lib/vacuum/cart.rb
+- lib/vacuum/cart_operations.rb
+- lib/vacuum/error.rb
+- lib/vacuum/locale.rb
+- lib/vacuum/lookup_operations.rb
+- lib/vacuum/request.rb
+- lib/vacuum/response.rb
+- lib/vacuum/search_operations.rb
+- lib/vacuum/version.rb
+- lib/vacuum.rb
+- LICENSE
+- README.md
+- spec/fixtures/http_response
+- spec/spec_helper.rb
+- spec/vacuum/builder_spec.rb
+- spec/vacuum/cart_operations_spec.rb
+- spec/vacuum/cart_spec.rb
+- spec/vacuum/lookup_operations_spec.rb
+- spec/vacuum/request_spec.rb
+- spec/vacuum/response_spec.rb
+- spec/vacuum/search_operations_spec.rb
+homepage: http://code.papercavalier.com/vacuum/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper to the Amazon Product Advertising API
+test_files:
+- spec/fixtures/http_response
+- spec/spec_helper.rb
+- spec/vacuum/builder_spec.rb
+- spec/vacuum/cart_operations_spec.rb
+- spec/vacuum/cart_spec.rb
+- spec/vacuum/lookup_operations_spec.rb
+- spec/vacuum/request_spec.rb
+- spec/vacuum/response_spec.rb
+- spec/vacuum/search_operations_spec.rb