asin 0.5.0 → 0.5.1

data/CHANGELOG.rdoc

@@ -3,6 +3,7 @@
 * move client to own file
 * use autoload
 * support for Hashie::Rash
+* new method browse_node
 
 == 0.4.0
 

data/README.rdoc

@@ -70,10 +70,6 @@ But you can also use the +instance+ method to get a proxy-object:
 
 There is an additional set of methods to support AWS cart operations:
 
-  #just require
-  require 'asin'
-  
-  # create an ASIN client
   client = ASIN::Client.instance
   
   # create a cart with an item
@@ -101,14 +97,26 @@ There is an additional set of methods to support AWS cart operations:
   cart.saved_items
   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
 
-== Item / Cart Response
+It's also possible to access browse nodes:
+
+  client = ASIN::Client.instance
+  
+  # create a cart with an item
+  node = client.browse_node('163357', :ResponseGroup => :TopSellers)
+  node.node_id
+  => '163357'
+  node.name
+  => 'Comedy'
+
+== Response Configuration
 
 ASIN is customizable in the way it returns Responses from Amazon. 
-By default it will return +SimpleItem+ or +SimpleCart+ instances,
+By default it will return +SimpleItem+, +SimpleCart+ or +SimpleNode+ instances,
 but you can override this behavior for using your custom Classes:
 
   client.configure :item_type => YourItemClass
   client.configure :cart_type => YourCartClass
+  client.configure :node_type => YourNodeClass
 
 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:

data/lib/asin.rb

@@ -1,7 +1,8 @@
 module ASIN
-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'
+  autoload :Client,         'asin/client'
+  autoload :SimpleItem,     'asin/simple_item'
+  autoload :SimpleCart,     'asin/simple_cart'
+  autoload :SimpleNode,     'asin/simple_node'
+  autoload :Version,        'asin/version'
+  autoload :Configuration,  'asin/configuration'
+end

data/lib/asin/client.rb

@@ -47,7 +47,7 @@ require 'base64'
 # == Further Configuration
 #
 # If you need more controll over the request that is sent to the
-# Amazon API (http://docs.amazonwebservices.com/AWSEcommerceService/4-0/),
+# Amazon API (http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/),
 # you can override some defaults or add additional query-parameters to the REST calls:
 #
 #   configure :host => 'webservices.amazon.de'
@@ -82,6 +82,22 @@ require 'base64'
 #   => true
 #   => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
 #
+# == Nodes
+#
+# In order to browse Amazon nodes, you can use +browse_node+ method:
+#
+#   node = browse_node('163357')
+#   node.node_id
+#   => '163357'
+#   node.name
+#   => 'Comedy'
+#   node.children
+#   node.ancestors
+#
+# you can configure the +:ResponseGroup+ option to your needs:
+#
+#   node = browse_node('163357', :ResponseGroup => :TopSellers)
+#
 module ASIN
   module Client
 
@@ -143,12 +159,12 @@ module ASIN
     #
     #   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/]
+    # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
     #
     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)}
+      arrayfy(response['ItemSearchResponse']['Items']['Item']).map {|item| handle_item(item)}
     end
 
     # Performs an +ItemSearch+ REST call against the Amazon API.
@@ -163,11 +179,30 @@ module ASIN
     #
     #   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/]
+    # Have a look at the different search index values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
     #
     def search(params={:SearchIndex => :Books, :ResponseGroup => :Medium})
       response = call(params.merge(:Operation => :ItemSearch))
-      (response['ItemSearchResponse']['Items']['Item'] || []).map {|item| handle_item(item)}
+      arrayfy(response['ItemSearchResponse']['Items']['Item']).map {|item| handle_item(item)}
+    end
+
+    # Performs an +BrowseNodeLookup+ REST call against the Amazon API.
+    #
+    # Expects a Hash of search params where and returns a +SimpleNode+:
+    #
+    #   node = browse_node '163357'
+    #
+    # ==== Options:
+    #
+    # Additional parameters for the API call like this:
+    #
+    #   browse_node('163357', :ResponseGroup => :TopSellers)
+    #
+    # Have a look at the different browse node values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
+    #
+    def browse_node(node_id, params={:ResponseGroup => :BrowseNodeInfo})
+      response = call(params.merge(:Operation => :BrowseNodeLookup, :BrowseNodeId => node_id))
+      handle_type(response['BrowseNodeLookupResponse']['BrowseNodes']['BrowseNode'], Configuration.node_type)
     end
 
     # Performs an +CartCreate+ REST call against the Amazon API.
@@ -182,7 +217,7 @@ module ASIN
     #
     #   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/]
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
     #
     def create_cart(*items)
       cart(:CartCreate, create_item_params(items))
@@ -210,7 +245,7 @@ module ASIN
     #
     #   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/]
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
     #
     def add_items(cart, *items)
       cart(:CartAdd, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
@@ -228,7 +263,7 @@ module ASIN
     #
     #   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/]
+    # Have a look at the different cart item operation values on the Amazon-Documentation[http://docs.amazonwebservices.com/AWSECommerceService/2010-11-01/DG/]
     #
     def update_items(cart, *items)
       cart(:CartModify, create_item_params(items).merge({:CartId => cart.cart_id, :HMAC => cart.hmac}))
@@ -245,6 +280,11 @@ module ASIN
     end
 
     private()
+    
+    def arrayfy(item)
+      return [] unless item
+      item.is_a?(Array) ? item : [item]
+    end
 
     def handle_item(item)
       handle_type(item, Configuration.item_type)
@@ -319,6 +359,10 @@ module ASIN
       # nice tutorial http://cloudcarpenters.com/blog/amazon_products_api_request_signing/
       params[:Service] = :AWSECommerceService
       params[:AWSAccessKeyId] = Configuration.key
+
+      params[:Version] = Configuration.version unless Configuration.version.empty?
+      params[:AssociateTag] = Configuration.associate_tag unless Configuration.associate_tag.empty?
+
       # utc timestamp needed for signing
       params[:Timestamp] = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
 

data/lib/asin/configuration.rb

@@ -6,7 +6,8 @@ module ASIN
     class << self
 
       attr_accessor :secret, :key, :host, :logger
-      attr_accessor :item_type, :cart_type
+      attr_accessor :item_type, :cart_type, :node_type
+      attr_accessor :version, :associate_tag
 
       # Rails initializer configuration.
       #
@@ -37,6 +38,9 @@ module ASIN
       # [logger] a different logger than logging to STDERR (nil for no logging)
       # [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
+      # [node_type] a different class for SimpleNode, use :mash / :rash for Hashie::Mash / Hashie::Rash or :raw for a plain hash
+      # [version] a custom version of the API calls. Default is 2010-11-01
+      # [associate_tag] your Amazon associate tag. Default is blank.
       #
       def configure(options={})
         init_config
@@ -69,13 +73,16 @@ module ASIN
 
         def init_config(force=false)
           return if @init && !force
-          @init       = true
-          @secret     = ''
-          @key        = ''
-          @host       = 'webservices.amazon.com'
-          @logger     = Logger.new(STDERR)
-          @item_type  = SimpleItem
-          @cart_type  = SimpleCart
+          @init          = true
+          @secret        = ''
+          @key           = ''
+          @host          = 'webservices.amazon.com'
+          @logger        = Logger.new(STDERR)
+          @item_type     = SimpleItem
+          @cart_type     = SimpleCart
+          @node_type     = SimpleNode
+          @version       = '2010-11-01'
+          @associate_tag = ''
         end
     end
   end

data/lib/asin/simple_node.rb

@@ -0,0 +1,44 @@
+require 'hashie'
+
+module ASIN
+
+  # =SimpleNode
+  #
+  # The +SimpleNode+ class is a wrapper for the Amazon XML-REST-Response.
+  #
+  # A Hashie::Mash is used for the internal data representation and can be accessed over the +raw+ attribute.
+  #
+  class SimpleNode
+
+    attr_reader :raw
+
+    def initialize(hash)
+      @raw = Hashie::Mash.new(hash)
+    end
+
+    def name
+      @raw.Name
+    end
+
+    def node_id
+      @raw.BrowseNodeId
+    end
+
+    def children
+      return [] unless @raw.Children
+      @raw.Children.BrowseNode.is_a?(Array) ? @raw.Children.BrowseNode : [@raw.Children.BrowseNode]
+    end
+
+    def ancestors
+      return [] unless @raw.Ancestors
+      @raw.Ancestors.BrowseNode.is_a?(Array) ? @raw.Ancestors.BrowseNode : [@raw.Ancestors.BrowseNode]
+    end
+
+    def top_item_set
+      return [] unless @raw.TopItemSet
+      @raw.TopItemSet.TopItem.is_a?(Array) ? @raw.TopItemSet.TopItem : [@raw.TopItemSet.TopItem]
+    end
+
+  end
+
+end

data/lib/asin/version.rb

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

data/spec/browse_node_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+module ASIN
+  describe ASIN do
+    before do
+      ASIN::Configuration.reset
+      @helper = ASIN::Client.instance
+      @helper.configure :logger => nil
+
+      @secret = ENV['ASIN_SECRET']
+      @key = ENV['ASIN_KEY']
+      puts "configure #{@secret} and #{@key} for this test"
+    end
+
+    context "lookup and search" do
+      before do
+        @helper.configure :secret => @secret, :key => @key
+      end
+
+      it "should lookup a book" do
+        item = @helper.browse_node(ANY_BROWSE_NODE_ID)
+        item.node_id.should eql(ANY_BROWSE_NODE_ID)
+        item.name.should eql('Comedy')
+      end
+    end
+  end
+end

data/spec/cart_spec.rb

@@ -2,7 +2,6 @@ require 'spec_helper'
 
 module ASIN
   describe ASIN do
-
     before do
       ASIN::Configuration.reset
       @helper = ASIN::Client.instance
@@ -17,7 +16,7 @@ module ASIN
     context "cart" do
 
       it "should create a cart" do
-        cart = @helper.create_cart({:asin => ANY_ASIN, :quantity => 1}, {:asin => OTHER_ASIN, :quantity => 2})
+        cart = @helper.create_cart({:asin => ANY_ASIN, :quantity => 1}, {:asin => ANY_OTHER_ASIN, :quantity => 2})
         cart.valid?.should be(true)
         cart.empty?.should be(false)
       end
@@ -47,7 +46,7 @@ module ASIN
         end
 
         it "should add items to a cart" do
-          cart = @helper.add_items(@cart, {:asin => OTHER_ASIN, :quantity => 2})
+          cart = @helper.add_items(@cart, {:asin => ANY_OTHER_ASIN, :quantity => 2})
           cart.valid?.should be(true)
           cart.empty?.should be(false)
           cart.items.should have(2).things

data/spec/search_spec.rb

@@ -103,7 +103,12 @@ module ASIN
         @helper.lookup(ANY_ASIN).item_attributes.title.should_not be_nil
       end
 
-      it "should search_keywords a book with fulltext" do
+      it "should search_keywords and handle a single result" do
+        items = @helper.search_keywords('0471317519')
+        items.first.title.should =~ /A Self-Teaching Guide/
+      end
+
+      it "should search_keywords book with fulltext" do
         items = @helper.search_keywords 'Learn', 'Objective-C'
         items.should have(10).things
 
@@ -112,7 +117,7 @@ module ASIN
 
       it "should search_keywords never mind music" do
         items = @helper.search_keywords 'nirvana', 'never mind', :SearchIndex => :Music
-        items.should have(9).things
+        items.should have(10).things
 
         items.first.title.should =~ /Nevermind/
       end

data/spec/spec_helper.rb

@@ -3,8 +3,9 @@ require 'rspec'
 require 'asin'
 require 'pp'
 
-ANY_ASIN    = '1430218150'
-OTHER_ASIN  = '1430216263'
+ANY_ASIN            = '1430218150'
+ANY_OTHER_ASIN      = '1430216263'
+ANY_BROWSE_NODE_ID  = '599826'
 
 RSpec.configure do |c|
   c.mock_with :rspec

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asin
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-07 00:00:00.000000000 +02:00
+date: 2011-08-03 00:00:00.000000000 +02:00
 default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: crack
-  requirement: &2153571760 !ruby/object:Gem::Requirement
+  requirement: &2153681520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 0.1.8
   type: :runtime
   prerelease: false
-  version_requirements: *2153571760
+  version_requirements: *2153681520
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &2153571260 !ruby/object:Gem::Requirement
+  requirement: &2153681020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +33,10 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2153571260
+  version_requirements: *2153681020
 - !ruby/object:Gem::Dependency
   name: httpi
-  requirement: &2153570800 !ruby/object:Gem::Requirement
+  requirement: &2153680560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -44,10 +44,10 @@ dependencies:
         version: 0.9.2
   type: :runtime
   prerelease: false
-  version_requirements: *2153570800
+  version_requirements: *2153680560
 - !ruby/object:Gem::Dependency
   name: httpclient
-  requirement: &2153570340 !ruby/object:Gem::Requirement
+  requirement: &2153680100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -55,10 +55,10 @@ dependencies:
         version: 2.2.0.2
   type: :development
   prerelease: false
-  version_requirements: *2153570340
+  version_requirements: *2153680100
 - !ruby/object:Gem::Dependency
   name: rash
-  requirement: &2168479800 !ruby/object:Gem::Requirement
+  requirement: &2153679640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -66,10 +66,10 @@ dependencies:
         version: 0.3.0
   type: :development
   prerelease: false
-  version_requirements: *2168479800
+  version_requirements: *2153679640
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2168479340 !ruby/object:Gem::Requirement
+  requirement: &2153679180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -77,10 +77,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *2168479340
+  version_requirements: *2153679180
 - !ruby/object:Gem::Dependency
   name: fuubar
-  requirement: &2168478880 !ruby/object:Gem::Requirement
+  requirement: &2153678720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -88,7 +88,7 @@ dependencies:
         version: 0.0.4
   type: :development
   prerelease: false
-  version_requirements: *2168478880
+  version_requirements: *2153678720
 description: Amazon Simple INterface.
 email:
 - phoetmail@googlemail.com
@@ -109,9 +109,11 @@ files:
 - lib/asin/configuration.rb
 - lib/asin/simple_cart.rb
 - lib/asin/simple_item.rb
+- lib/asin/simple_node.rb
 - lib/asin/version.rb
 - rakefile.rb
 - spec/asin.yml
+- spec/browse_node_spec.rb
 - spec/cart_spec.rb
 - spec/search_spec.rb
 - spec/spec_helper.rb
@@ -142,6 +144,7 @@ specification_version: 3
 summary: Simple interface to AWS Lookup, Search and Cart operations.
 test_files:
 - spec/asin.yml
+- spec/browse_node_spec.rb
 - spec/cart_spec.rb
 - spec/search_spec.rb
 - spec/spec_helper.rb