asin 0.4.0 → 0.5.0

data/CHANGELOG.rdoc

@@ -1,4 +1,10 @@
-== 0.4.0.beta2
+== 0.5.0
+
+* move client to own file
+* use autoload
+* support for Hashie::Rash
+
+== 0.4.0
 
 * add configuration option for item/cart class
 * add more functionality to item class

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    asin (0.4.0)
+    asin (0.5.0)
       crack (~> 0.1.8)
       hashie (~> 1.0.0)
       httpi (~> 0.9.2)
@@ -9,29 +9,31 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    chalofa_ruby-progressbar (0.0.9.1)
     crack (0.1.8)
     diff-lcs (1.1.2)
-    fuubar (0.0.4)
-      chalofa_ruby-progressbar (~> 0.0.9)
+    fuubar (0.0.5)
       rspec (~> 2.0)
       rspec-instafail (~> 0.1.4)
+      ruby-progressbar (~> 0.0.10)
     hashie (1.0.0)
     httpclient (2.2.0.2)
     httpi (0.9.4)
       pyu-ntlm-http (>= 0.1.3.1)
       rack
     pyu-ntlm-http (0.1.3.1)
-    rack (1.2.2)
+    rack (1.3.0)
+    rash (0.3.0)
+      hashie (~> 1.0.0)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)
       rspec-expectations (~> 2.6.0)
       rspec-mocks (~> 2.6.0)
-    rspec-core (2.6.1)
+    rspec-core (2.6.4)
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
-    rspec-instafail (0.1.7)
+    rspec-instafail (0.1.8)
     rspec-mocks (2.6.0)
+    ruby-progressbar (0.0.10)
 
 PLATFORMS
   ruby
@@ -40,4 +42,5 @@ DEPENDENCIES
   asin!
   fuubar (~> 0.0.4)
   httpclient (~> 2.2.0.2)
+  rash (~> 0.3.0)
   rspec (~> 2.6.0)

data/README.rdoc

@@ -39,13 +39,13 @@ ASIN is designed as a module, so you can include it into any object you like:
   # lookup an ASIN
   lookup '1430218150'
 
-But you can also use the +client+ method to get a client-object:
+But you can also use the +instance+ method to get a proxy-object:
 
   # just require
   require 'asin'
   
   # create an ASIN client
-  client = ASIN.client
+  client = ASIN::Client.instance
   
   # lookup an item with the amazon standard identification number (asin)
   item = client.lookup '1430218150'
@@ -74,7 +74,7 @@ There is an additional set of methods to support AWS cart operations:
   require 'asin'
   
   # create an ASIN client
-  client = ASIN.client
+  client = ASIN::Client.instance
   
   # create a cart with an item
   cart = client.create_cart({:asin => '1430218150', :quantity => 1})
@@ -101,6 +101,20 @@ There is an additional set of methods to support AWS cart operations:
   cart.saved_items
   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
 
+== Item / Cart Response
+
+ASIN is customizable in the way it returns Responses from Amazon. 
+By default it will return +SimpleItem+ or +SimpleCart+ instances,
+but you can override this behavior for using your custom Classes:
+
+  client.configure :item_type => YourItemClass
+  client.configure :cart_type => YourCartClass
+
+You can also use built-in +:raw+, +:mash+ or +:rash+ types.
+Since +rash+ is an additional library, you need to add it to your gemfile if you want to use it:
+
+  gem 'rash'
+
 == HTTPI
 
 ASIN uses HTTPI[https://github.com/rubiii/httpi] as a HTTP-Client adapter.
@@ -113,4 +127,4 @@ As a default HTTPI uses _httpclient_ so you should add that dependency to your p
 
 Have a look at the RDOC[http://rdoc.info/projects/phoet/asin] for this project, if you want further information.
 
-For more information on the REST calls, have a look at the whole Amazon E-Commerce-API[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/].
+For more information on the REST calls, have a look at the whole Amazon E-Commerce-API[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/].

data/asin.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |s|
   s.add_dependency('httpi', '~> 0.9.2')
   
   s.add_development_dependency('httpclient', '~> 2.2.0.2')
+  s.add_development_dependency('rash', '~> 0.3.0')
   s.add_development_dependency('rspec', '~> 2.6.0')
   s.add_development_dependency('fuubar', '~> 0.0.4')
 end

data/lib/asin.rb

@@ -1,332 +1,7 @@
-# -*- coding: utf-8 -*-
-require 'httpi'
-require 'crack/xml'
-require 'cgi'
-require 'base64'
-require 'logger'
-
-require 'asin/item'
-require 'asin/cart'
-require 'asin/version'
-require 'asin/configuration'
-
-# ASIN (Amazon Simple INterface) is a gem for easy access of the Amazon E-Commerce-API.
-# It is simple to configure and use. Since it's very small and flexible, it is easy to extend it to your needs.
-#
-# Author::    Peter Schröder  (mailto:phoetmail@googlemail.com)
-#
-# == Usage
-#
-# The ASIN module is designed as a mixin.
-#
-#   require 'asin'
-#   include ASIN
-#
-# In order to use the Amazon API properly, you need to be a registered user (http://aws.amazon.com).
-#
-# The registration process will give you a +secret-key+ and an +access-key+ (AWSAccessKeyId).
-#
-# Both are needed to use ASIN (see Configuration for more details):
-#
-#   configure :secret => 'your-secret', :key => 'your-key'
-#
-# == Search
-#
-# After configuring your environment you can call the +lookup+ method to retrieve an +SimpleItem+ via the
-# Amazon Standard Identification Number (ASIN):
-#
-#   item = lookup '1430218150'
-#   item.title
-#   => "Learn Objective-C on the Mac (Learn Series)"
-#
-# OR search with fulltext/ASIN/ISBN
-#
-#   items = search 'Learn Objective-C'
-#   items.first.title
-#   => "Learn Objective-C on the Mac (Learn Series)"
-#
-# The +SimpleItem+ uses a Hashie::Mash as its internal data representation and you can get fetched data from it:
-#
-#   item.raw.ItemAttributes.ListPrice.FormattedPrice
-#   => "$39.99"
-#
-# == Further Configuration
-#
-# If you need more controll over the request that is sent to the
-# Amazon API (http://docs.amazonwebservices.com/AWSEcommerceService/4-0/),
-# you can override some defaults or add additional query-parameters to the REST calls:
-#
-#   configure :host => 'webservices.amazon.de'
-#   lookup(asin, :ResponseGroup => :Medium)
-#
-# == Cart
-#
-# ASIN helps with AWS cart-operations.
-# It currently supports the CartCreate, CartGet, CartAdd, CartModify and CartClear operations:
-#
-#   cart = create_cart({:asin => '1430218150', :quantity => 1})
-#   cart.valid?
-#   cart.items
-#   => true
-#   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
-#
-#   cart = get_cart('176-9182855-2326919', 'KgeVCA0YJTbuN/7Ibakrk/KnHWA=')
-#   cart.empty?
-#   => false
-#
-#   cart = clear_cart(cart)
-#   cart.empty?
-#   => true
-#
-#   cart = add_items(cart, {:asin => '1430216263', :quantity => 2})
-#   cart.empty?
-#   => false
-#
-#   cart = update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :action => :SaveForLater}, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
-#   cart.valid?
-#   cart.saved_items
-#   => true
-#   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
-#
 module ASIN
-
-  DIGEST  = OpenSSL::Digest::Digest.new('sha256')
-  PATH    = '/onca/xml'
-
-  # Convenience method to create an ASIN client.
-  #
-  # A client is not necessary though, you can simply include the ASIN module otherwise.
-  #
-  def self.client
-    client = Object.new
-    client.extend ASIN
-    client
-  end
-
-  # Configures the basic request parameters for ASIN.
-  #
-  # Expects at least +secret+ and +key+ for the API call:
-  #
-  #   configure :secret => 'your-secret', :key => 'your-key'
-  #
-  # See ASIN::Configuration for more infos.
-  #
-  def configure(options={})
-    Configuration.configure(options)
-  end
-
-  # Performs an +ItemLookup+ REST call against the Amazon API.
-  #
-  # Expects an ASIN (Amazon Standard Identification Number) and returns an +SimpleItem+:
-  #
-  #   item = lookup '1430218150'
-  #   item.title
-  #   => "Learn Objective-C on the Mac (Learn Series)"
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   lookup(asin, :ResponseGroup => :Medium)
-  #
-  def lookup(asin, params={:ResponseGroup => :Medium})
-    response = call(params.merge(:Operation => :ItemLookup, :ItemId => asin))
-    handle_item(response['ItemLookupResponse']['Items']['Item'])
-  end
-
-  # Performs an +ItemSearch+ REST call against the Amazon API.
-  #
-  # Expects a search-string which can be an arbitrary array of strings (ASINs f.e.) and returns a list of +SimpleItem+s:
-  #
-  #   items = search_keywords 'Learn', 'Objective-C'
-  #   items.first.title
-  #   => "Learn Objective-C on the Mac (Learn Series)"
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   search_keywords('nirvana', 'never mind', :SearchIndex => :Music)
-  #
-  # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
-  #
-  def search_keywords(*keywords)
-    params = keywords.last.is_a?(Hash) ? keywords.pop : {:SearchIndex => :Books, :ResponseGroup => :Medium}
-    response = call(params.merge(:Operation => :ItemSearch, :Keywords => keywords.join(' ')))
-    (response['ItemSearchResponse']['Items']['Item'] || []).map {|item| handle_item(item)}
-  end
-
-  # Performs an +ItemSearch+ REST call against the Amazon API.
-  #
-  # Expects a Hash of search params where and returns a list of +SimpleItem+s:
-  #
-  #   items = search :SearchIndex => :Music
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   search(:Keywords => 'nirvana', :SearchIndex => :Music)
-  #
-  # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
-  #
-  def search(params={:SearchIndex => :Books, :ResponseGroup => :Medium})
-    response = call(params.merge(:Operation => :ItemSearch))
-    (response['ItemSearchResponse']['Items']['Item'] || []).map {|item| handle_item(item)}
-  end
-
-  # Performs an +CartCreate+ REST call against the Amazon API.
-  #
-  # Expects one ore more item-hashes and returns a +SimpleCart+:
-  #
-  #   cart = create_cart({:asin => '1430218150', :quantity => 1})
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   create_cart({:asin => '1430218150', :quantity => 1}, {:asin => '1430216263', :quantity => 1, :action => :SaveForLater})
-  #
-  # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
-  #
-  def create_cart(*items)
-    cart(:CartCreate, create_item_params(items))
-  end
-
-  # Performs an +CartGet+ REST call against the Amazon API.
-  #
-  # Expects the CartId and the HMAC to identify the returning +SimpleCart+:
-  #
-  #   cart = get_cart('176-9182855-2326919', 'KgeVCA0YJTbuN/7Ibakrk/KnHWA=')
-  #
-  def get_cart(cart_id, hmac)
-    cart(:CartGet, {:CartId => cart_id, :HMAC => hmac})
-  end
-
-  # Performs an +CartAdd+ REST call against the Amazon API.
-  #
-  # Expects a +SimpleCart+ created with +create_cart+ and one ore more Item-Hashes and returns an updated +SimpleCart+:
-  #
-  #   cart = add_items(cart, {:asin => '1430216263', :quantity => 2})
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   add_items(cart, {:asin => '1430218150', :quantity => 1}, {:asin => '1430216263', :quantity => 1, :action => :SaveForLater})
-  #
-  # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
-  #
-  def add_items(cart, *items)
-    cart(:CartAdd, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
-  end
-
-  # Performs an +CartModify+ REST call against the Amazon API.
-  #
-  # Expects a +SimpleCart+ created with +create_cart+ and one ore more Item-Hashes to modify and returns an updated +SimpleCart+:
-  #
-  #   cart = update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
-  #
-  # ==== Options:
-  #
-  # Additional parameters for the API call like this:
-  #
-  #   update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :action => :SaveForLater}, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
-  #
-  # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
-  #
-  def update_items(cart, *items)
-    cart(:CartModify, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
-  end
-
-  # Performs an +CartClear+ REST call against the Amazon API.
-  #
-  # Expects a +SimpleCart+ created with +create_cart+ and returns an empty +SimpleCart+:
-  #
-  #   cart = clear_cart(cart)
-  #
-  def clear_cart(cart)
-    cart(:CartClear, {:CartId => cart.cart_id, :HMAC => cart.hmac})
-  end
-
-  private
-  
-    def handle_item(item)
-      Configuration.item_type.is_a?(Class) ? Configuration.item_type.new(item) : item
-    end
-
-    def create_item_params(items)
-      keyword_mappings = {
-        :asin               => 'ASIN',
-        :quantity           => 'Quantity',
-        :cart_item_id       => 'CartItemId',
-        :offer_listing_id   => 'OfferListingId',
-        :action             => 'Action'
-      }
-      params = {}
-      items.each_with_index do |item, i|
-        item.each do |key, value|
-          next unless keyword = keyword_mappings[key]
-          params["Item.#{i}.#{keyword}"] = value.to_s
-        end
-      end
-      params
-    end
-
-    def cart(operation, params={})
-      response = call(params.merge(:Operation => operation))
-      cart = response["#{operation}Response"]['Cart']
-      Configuration.cart_type.is_a?(Class) ? Configuration.cart_type.new(cart) : cart
-    end
-
-
-    def credentials_valid?
-      Configuration.secret && Configuration.key
-    end
-
-    def call(params)
-      raise "you have to configure ASIN: 'configure :secret => 'your-secret', :key => 'your-key''" unless credentials_valid?
-
-      log(:debug, "calling with params=#{params}")
-      signed = create_signed_query_string(params)
-
-      url = "http://#{Configuration.host}#{PATH}?#{signed}"
-      log(:info, "performing rest call to url='#{url}'")
-
-      response = HTTPI.get(url)
-      if response.code == 200
-        # force utf-8 chars, works only on 1.9 string
-        resp = response.body
-        resp = resp.force_encoding('UTF-8') if resp.respond_to? :force_encoding
-        log(:debug, "got response='#{resp}'")
-        Crack::XML.parse(resp)
-      else
-        log(:error, "got response='#{response.body}'")
-        raise "request failed with response-code='#{response.code}'"
-      end
-    end
-
-    def create_signed_query_string(params)
-      # nice tutorial http://cloudcarpenters.com/blog/amazon_products_api_request_signing/
-      params[:Service] = :AWSECommerceService
-      params[:AWSAccessKeyId] = Configuration.key
-      # utc timestamp needed for signing
-      params[:Timestamp] = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
-
-      # signing needs to order the query alphabetically
-      query = params.map{|key, value| "#{key}=#{CGI.escape(value.to_s)}" }.sort.join('&').gsub('+','%20')
-
-      # yeah, you really need to sign the get-request not the query
-      request_to_sign = "GET\n#{Configuration.host}\n#{PATH}\n#{query}"
-      hmac = OpenSSL::HMAC.digest(DIGEST, Configuration.secret, request_to_sign)
-
-      # don't forget to remove the newline from base64
-      signature = CGI.escape(Base64.encode64(hmac).chomp)
-      "#{query}&Signature=#{signature}"
-    end
-
-    def log(severity, message)
-      Configuration.logger.send severity, message if Configuration.logger
-    end
-
 end
+ASIN.autoload :Client,         'asin/client'
+ASIN.autoload :SimpleItem,     'asin/simple_item'
+ASIN.autoload :SimpleCart,     'asin/simple_cart'
+ASIN.autoload :Version,        'asin/version'
+ASIN.autoload :Configuration,  'asin/configuration'

data/lib/asin/client.rb

@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+require 'httpi'
+require 'crack/xml'
+require 'cgi'
+require 'base64'
+
+# ASIN (Amazon Simple INterface) is a gem for easy access of the Amazon E-Commerce-API.
+# It is simple to configure and use. Since it's very small and flexible, it is easy to extend it to your needs.
+#
+# Author::    Peter Schröder  (mailto:phoetmail@googlemail.com)
+#
+# == Usage
+#
+# The ASIN module is designed as a mixin.
+#
+#   require 'asin'
+#   include ASIN::Client
+#
+# In order to use the Amazon API properly, you need to be a registered user (http://aws.amazon.com).
+#
+# The registration process will give you a +secret-key+ and an +access-key+ (AWSAccessKeyId).
+#
+# Both are needed to use ASIN (see Configuration for more details):
+#
+#   configure :secret => 'your-secret', :key => 'your-key'
+#
+# == Search
+#
+# After configuring your environment you can call the +lookup+ method to retrieve an +SimpleItem+ via the
+# Amazon Standard Identification Number (ASIN):
+#
+#   item = lookup '1430218150'
+#   item.title
+#   => "Learn Objective-C on the Mac (Learn Series)"
+#
+# OR search with fulltext/ASIN/ISBN
+#
+#   items = search 'Learn Objective-C'
+#   items.first.title
+#   => "Learn Objective-C on the Mac (Learn Series)"
+#
+# The +SimpleItem+ uses a Hashie::Mash as its internal data representation and you can get fetched data from it:
+#
+#   item.raw.ItemAttributes.ListPrice.FormattedPrice
+#   => "$39.99"
+#
+# == Further Configuration
+#
+# If you need more controll over the request that is sent to the
+# Amazon API (http://docs.amazonwebservices.com/AWSEcommerceService/4-0/),
+# you can override some defaults or add additional query-parameters to the REST calls:
+#
+#   configure :host => 'webservices.amazon.de'
+#   lookup(asin, :ResponseGroup => :Medium)
+#
+# == Cart
+#
+# ASIN helps with AWS cart-operations.
+# It currently supports the CartCreate, CartGet, CartAdd, CartModify and CartClear operations:
+#
+#   cart = create_cart({:asin => '1430218150', :quantity => 1})
+#   cart.valid?
+#   cart.items
+#   => true
+#   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
+#
+#   cart = get_cart('176-9182855-2326919', 'KgeVCA0YJTbuN/7Ibakrk/KnHWA=')
+#   cart.empty?
+#   => false
+#
+#   cart = clear_cart(cart)
+#   cart.empty?
+#   => true
+#
+#   cart = add_items(cart, {:asin => '1430216263', :quantity => 2})
+#   cart.empty?
+#   => false
+#
+#   cart = update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :action => :SaveForLater}, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
+#   cart.valid?
+#   cart.saved_items
+#   => true
+#   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
+#
+module ASIN
+  module Client
+
+    DIGEST  = OpenSSL::Digest::Digest.new('sha256')
+    PATH    = '/onca/xml'
+
+    # Convenience method to create an ASIN client.
+    #
+    # An instance is not necessary though, you can simply include the ASIN module otherwise.
+    #
+    def self.instance
+      ins = Object.new
+      ins.extend ASIN::Client
+      ins
+    end
+
+    # Configures the basic request parameters for ASIN.
+    #
+    # Expects at least +secret+ and +key+ for the API call:
+    #
+    #   configure :secret => 'your-secret', :key => 'your-key'
+    #
+    # See ASIN::Configuration for more infos.
+    #
+    def configure(options={})
+      Configuration.configure(options)
+    end
+
+    # Performs an +ItemLookup+ REST call against the Amazon API.
+    #
+    # Expects an ASIN (Amazon Standard Identification Number) and returns an +SimpleItem+:
+    #
+    #   item = lookup '1430218150'
+    #   item.title
+    #   => "Learn Objective-C on the Mac (Learn Series)"
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   lookup(asin, :ResponseGroup => :Medium)
+    #
+    def lookup(asin, params={:ResponseGroup => :Medium})
+      response = call(params.merge(:Operation => :ItemLookup, :ItemId => asin))
+      handle_item(response['ItemLookupResponse']['Items']['Item'])
+    end
+
+    # Performs an +ItemSearch+ REST call against the Amazon API.
+    #
+    # Expects a search-string which can be an arbitrary array of strings (ASINs f.e.) and returns a list of +SimpleItem+s:
+    #
+    #   items = search_keywords 'Learn', 'Objective-C'
+    #   items.first.title
+    #   => "Learn Objective-C on the Mac (Learn Series)"
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   search_keywords('nirvana', 'never mind', :SearchIndex => :Music)
+    #
+    # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
+    #
+    def search_keywords(*keywords)
+      params = keywords.last.is_a?(Hash) ? keywords.pop : {:SearchIndex => :Books, :ResponseGroup => :Medium}
+      response = call(params.merge(:Operation => :ItemSearch, :Keywords => keywords.join(' ')))
+      (response['ItemSearchResponse']['Items']['Item'] || []).map {|item| handle_item(item)}
+    end
+
+    # Performs an +ItemSearch+ REST call against the Amazon API.
+    #
+    # Expects a Hash of search params where and returns a list of +SimpleItem+s:
+    #
+    #   items = search :SearchIndex => :Music
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   search(:Keywords => 'nirvana', :SearchIndex => :Music)
+    #
+    # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
+    #
+    def search(params={:SearchIndex => :Books, :ResponseGroup => :Medium})
+      response = call(params.merge(:Operation => :ItemSearch))
+      (response['ItemSearchResponse']['Items']['Item'] || []).map {|item| handle_item(item)}
+    end
+
+    # Performs an +CartCreate+ REST call against the Amazon API.
+    #
+    # Expects one ore more item-hashes and returns a +SimpleCart+:
+    #
+    #   cart = create_cart({:asin => '1430218150', :quantity => 1})
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   create_cart({:asin => '1430218150', :quantity => 1}, {:asin => '1430216263', :quantity => 1, :action => :SaveForLater})
+    #
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
+    #
+    def create_cart(*items)
+      cart(:CartCreate, create_item_params(items))
+    end
+
+    # Performs an +CartGet+ REST call against the Amazon API.
+    #
+    # Expects the CartId and the HMAC to identify the returning +SimpleCart+:
+    #
+    #   cart = get_cart('176-9182855-2326919', 'KgeVCA0YJTbuN/7Ibakrk/KnHWA=')
+    #
+    def get_cart(cart_id, hmac)
+      cart(:CartGet, {:CartId => cart_id, :HMAC => hmac})
+    end
+
+    # Performs an +CartAdd+ REST call against the Amazon API.
+    #
+    # Expects a +SimpleCart+ created with +create_cart+ and one ore more Item-Hashes and returns an updated +SimpleCart+:
+    #
+    #   cart = add_items(cart, {:asin => '1430216263', :quantity => 2})
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   add_items(cart, {:asin => '1430218150', :quantity => 1}, {:asin => '1430216263', :quantity => 1, :action => :SaveForLater})
+    #
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
+    #
+    def add_items(cart, *items)
+      cart(:CartAdd, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
+    end
+
+    # Performs an +CartModify+ REST call against the Amazon API.
+    #
+    # Expects a +SimpleCart+ created with +create_cart+ and one ore more Item-Hashes to modify and returns an updated +SimpleCart+:
+    #
+    #   cart = update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :action => :SaveForLater}, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
+    #
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSEcommerceService/4-0/]
+    #
+    def update_items(cart, *items)
+      cart(:CartModify, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
+    end
+
+    # Performs an +CartClear+ REST call against the Amazon API.
+    #
+    # Expects a +SimpleCart+ created with +create_cart+ and returns an empty +SimpleCart+:
+    #
+    #   cart = clear_cart(cart)
+    #
+    def clear_cart(cart)
+      cart(:CartClear, {:CartId => cart.cart_id, :HMAC => cart.hmac})
+    end
+
+    private()
+
+    def handle_item(item)
+      handle_type(item, Configuration.item_type)
+    end
+
+    def handle_type(data, type)
+      if type.is_a?(Class)
+        type.new(data)
+      elsif type == :mash
+        require 'hashie'
+        Hashie::Mash.new(data)
+      elsif type == :rash
+        require 'rash'
+        Hashie::Rash.new(data)
+      else
+        data
+      end
+    end
+
+    def create_item_params(items)
+      keyword_mappings = {
+        :asin               => 'ASIN',
+        :quantity           => 'Quantity',
+        :cart_item_id       => 'CartItemId',
+        :offer_listing_id   => 'OfferListingId',
+        :action             => 'Action'
+      }
+      params = {}
+      items.each_with_index do |item, i|
+        item.each do |key, value|
+          next unless keyword = keyword_mappings[key]
+          params["Item.#{i}.#{keyword}"] = value.to_s
+        end
+      end
+      params
+    end
+
+    def cart(operation, params={})
+      response = call(params.merge(:Operation => operation))
+      cart = response["#{operation}Response"]['Cart']
+      handle_type(cart, Configuration.cart_type)
+    end
+
+
+    def credentials_valid?
+      Configuration.secret && Configuration.key
+    end
+
+    def call(params)
+      raise "you have to configure ASIN: 'configure :secret => 'your-secret', :key => 'your-key''" unless credentials_valid?
+
+      log(:debug, "calling with params=#{params}")
+      signed = create_signed_query_string(params)
+
+      url = "http://#{Configuration.host}#{PATH}?#{signed}"
+      log(:info, "performing rest call to url='#{url}'")
+
+      response = HTTPI.get(url)
+      if response.code == 200
+        # force utf-8 chars, works only on 1.9 string
+        resp = response.body
+        resp = resp.force_encoding('UTF-8') if resp.respond_to? :force_encoding
+        log(:debug, "got response='#{resp}'")
+        Crack::XML.parse(resp)
+      else
+        log(:error, "got response='#{response.body}'")
+        raise "request failed with response-code='#{response.code}'"
+      end
+    end
+
+    def create_signed_query_string(params)
+      # nice tutorial http://cloudcarpenters.com/blog/amazon_products_api_request_signing/
+      params[:Service] = :AWSECommerceService
+      params[:AWSAccessKeyId] = Configuration.key
+      # utc timestamp needed for signing
+      params[:Timestamp] = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+      # signing needs to order the query alphabetically
+      query = params.map{|key, value| "#{key}=#{CGI.escape(value.to_s)}" }.sort.join('&').gsub('+','%20')
+
+      # yeah, you really need to sign the get-request not the query
+      request_to_sign = "GET\n#{Configuration.host}\n#{PATH}\n#{query}"
+      hmac = OpenSSL::HMAC.digest(DIGEST, Configuration.secret, request_to_sign)
+
+      # don't forget to remove the newline from base64
+      signature = CGI.escape(Base64.encode64(hmac).chomp)
+      "#{query}&Signature=#{signature}"
+    end
+
+    def log(severity, message)
+      Configuration.logger.send severity, message if Configuration.logger
+    end
+  end
+end

data/lib/asin/configuration.rb

@@ -1,4 +1,5 @@
 require "yaml"
+require 'logger'
 
 module ASIN
   class Configuration
@@ -34,8 +35,8 @@ module ASIN
       # [key] the API access key
       # [host] the host, which defaults to 'webservices.amazon.com'
       # [logger] a different logger than logging to STDERR (nil for no logging)
-      # [item_type] a different class for SimpleItem, use :raw for a plain mash
-      # [cart_type] a different class for SimpleCart, use :raw for a plain mash
+      # [item_type] a different class for SimpleItem, use :mash / :rash for Hashie::Mash / Hashie::Rash or :raw for a plain hash
+      # [cart_type] a different class for SimpleCart, use :mash / :rash for Hashie::Mash / Hashie::Rash or :raw for a plain hash
       #
       def configure(options={})
         init_config

data/lib/asin/version.rb

@@ -1,3 +1,3 @@
 module ASIN
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/rakefile.rb

@@ -11,7 +11,7 @@ end
 
 Rake::RDocTask.new(:rdoc_dev) do |rd|
   rd.rdoc_files.include(File.readlines('.document').map(&:strip))
-  rd.options + ['-a', '--inline-source', '--charset=UTF-8']
+  rd.options + ['-a', '--line-numbers', '--charset=UTF-8']
 end
 
 task :default=>:spec

data/spec/cart_spec.rb

@@ -5,7 +5,7 @@ module ASIN
 
     before do
       ASIN::Configuration.reset
-      @helper = ASIN.client
+      @helper = ASIN::Client.instance
       @helper.configure :logger => nil
 
       @secret = ENV['ASIN_SECRET']

data/spec/search_spec.rb

@@ -4,7 +4,7 @@ module ASIN
   describe ASIN do
     before do
       ASIN::Configuration.reset
-      @helper = ASIN.client
+      @helper = ASIN::Client.instance
       @helper.configure :logger => nil
 
       @secret = ENV['ASIN_SECRET']
@@ -93,6 +93,16 @@ module ASIN
         @helper.lookup(ANY_ASIN)['ItemAttributes']['Title'].should_not be_nil
       end
 
+      it "should return a mash value" do
+        @helper.configure :item_type => :mash
+        @helper.lookup(ANY_ASIN).ItemAttributes.Title.should_not be_nil
+      end
+
+      it "should return a rash value" do
+        @helper.configure :item_type => :rash
+        @helper.lookup(ANY_ASIN).item_attributes.title.should_not be_nil
+      end
+
       it "should search_keywords a book with fulltext" do
         items = @helper.search_keywords 'Learn', 'Objective-C'
         items.should have(10).things
@@ -102,7 +112,7 @@ module ASIN
 
       it "should search_keywords never mind music" do
         items = @helper.search_keywords 'nirvana', 'never mind', :SearchIndex => :Music
-        items.should have(8).things
+        items.should have(9).things
 
         items.first.title.should =~ /Nevermind/
       end

metadata

@@ -1,94 +1,101 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: asin
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.5.0
   prerelease: 
-  version: 0.4.0
 platform: ruby
-authors: 
-- "Peter Schr\xC3\xB6der"
+authors:
+- Peter Schröder
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-05-20 00:00:00 +02:00
+date: 2011-07-07 00:00:00.000000000 +02:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+dependencies:
+- !ruby/object:Gem::Dependency
   name: crack
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2153571760 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 0.1.8
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: hashie
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2153571760
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: &2153571260 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.0.0
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: httpi
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2153571260
+- !ruby/object:Gem::Dependency
+  name: httpi
+  requirement: &2153570800 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 0.9.2
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: httpclient
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *2153570800
+- !ruby/object:Gem::Dependency
+  name: httpclient
+  requirement: &2153570340 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 2.2.0.2
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *2153570340
+- !ruby/object:Gem::Dependency
+  name: rash
+  requirement: &2168479800 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :development
+  prerelease: false
+  version_requirements: *2168479800
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2168479340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
         version: 2.6.0
   type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: fuubar
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *2168479340
+- !ruby/object:Gem::Dependency
+  name: fuubar
+  requirement: &2168478880 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 0.0.4
   type: :development
-  version_requirements: *id006
+  prerelease: false
+  version_requirements: *2168478880
 description: Amazon Simple INterface.
-email: 
+email:
 - phoetmail@googlemail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .document
 - .gitignore
 - .rvmrc
@@ -98,9 +105,10 @@ files:
 - README.rdoc
 - asin.gemspec
 - lib/asin.rb
-- lib/asin/cart.rb
+- lib/asin/client.rb
 - lib/asin/configuration.rb
-- lib/asin/item.rb
+- lib/asin/simple_cart.rb
+- lib/asin/simple_item.rb
 - lib/asin/version.rb
 - rakefile.rb
 - spec/asin.yml
@@ -110,32 +118,29 @@ files:
 has_rdoc: true
 homepage: http://github.com/phoet/asin
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: asin
-rubygems_version: 1.5.2
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Simple interface to AWS Lookup, Search and Cart operations.
-test_files: 
+test_files:
 - spec/asin.yml
 - spec/cart_spec.rb
 - spec/search_spec.rb