asin 0.0.5 → 0.0.6

data/lib/asin.rb

@@ -4,8 +4,53 @@ 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
+# 
+# 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:
+# 
+#   configure :secret => 'your-secret', :key => 'your-key'
+# 
+# After configuring your environment you can call the +lookup+ method to retrieve an +Item+ via the Amazon Standard Identification Number (ASIN):
+# 
+#   item = lookup '1430218150'
+#   item.title
+#   => "Learn Objective-C on the Mac (Learn Series)"
+# 
+# The +Item+ 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)
+# 
 module ASIN
 
+  # =Item
+  # 
+  # The +Item+ 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 Item
 
     attr_reader :raw
@@ -20,6 +65,18 @@ module ASIN
 
   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'
+  # 
+  # ==== Options:
+  # 
+  # [secret] the API secret key
+  # [key] the API access key
+  # [host] the host, which defaults to 'webservices.amazon.com'
+  # 
   def configure(options={})
     @options = {
       :host => 'webservices.amazon.com', 
@@ -31,12 +88,28 @@ module ASIN
     @options.merge! options
   end
 
+  # Performs an +ItemLookup+ REST call against the Amazon API.
+  # 
+  # Expects an ASIN (Amazon Standard Identification Number) and returns an +Item+:
+  # 
+  #   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={})
     Item.new(call(params.merge(:Operation => :ItemLookup, :ItemId => asin)))
   end
 
+  private
+
   def call(params)
-    configure if @options.nil?
+    raise "you have to configure ASIN: 'configure :secret => 'your-secret', :key => 'your-key''" if @options.nil?
     signed = create_signed_query_string(params)
     resp = HTTPClient.new.get_content("http://#{@options[:host]}#{@options[:path]}?#{signed}")
     resp = resp.force_encoding('UTF-8') # shady workaround cause amazon returns bad utf-8 chars

data/readme.textile

@@ -10,11 +10,23 @@ The code currently runs only on __Ruby 1.9__ due to encoding issues with the Ama
 
 h2. Usage
 
-<pre>
+<pre lang="ruby">
 require 'asin'
 include ASIN
+# use the configure method to setup your api credentials
 configure :secret => 'your-secret', :key => 'your-key'
-item = lookup '1430218150
+# lookup an item with the amazon standard identification number (asin)
+item = lookup '1430218150'
+# have a look at the title of the item
 item.title
 => Learn Objective-C on the Mac (Learn Series)
-</pre>
+# access the internal data representation (Hashie::Mash)
+item.raw.ItemAttributes.ListPrice.FormattedPrice
+=> $39.99
+</pre>
+
+h2. TODO
+
+* Logging
+* More Docs
+* More Tests

data/test/test_asin.rb

@@ -1,5 +1,7 @@
 require 'test_helper'
 
+ANY_ASIN = '1430218150'
+
 class TestAsin < Test::Unit::TestCase
 
   def setup
@@ -7,11 +9,17 @@ class TestAsin < Test::Unit::TestCase
     @helper.extend ASIN
   end
 
-  # comment in and add your key to test real calls
-  # def test_r_type_from_engine  
-  #   @helper.configure :secret => 'your-secret', :key => 'your-key'
-  #   p item = @helper.lookup('1430218150')
-  #   assert_match(/Learn Objective/, item.title)
-  # end
+  def test_lookup_with_configured_asin
+    secret = ENV['ASIN_SECRET']
+    key = ENV['ASIN_KEY']
+    puts "configure #{secret} and #{key} for this test"
+    @helper.configure :secret => secret, :key => key
+    p item = @helper.lookup(ANY_ASIN)
+    assert_match(/Learn Objective/, item.title)
+  end
+  
+  def test_error_with_not_called_configure
+    assert_raise(RuntimeError) { @helper.lookup ANY_ASIN }
+  end
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: asin
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - "Peter Schr\xC3\xB6der"
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-06 00:00:00 +02:00
+date: 2010-07-13 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -66,7 +66,7 @@ dependencies:
         version: 2.1.0
   type: :runtime
   version_requirements: *id003
-description: Amazon Simple INterface or whatever you want to call this
+description: Amazon Simple INterface or whatever you want to call this.
 email: phoetmail@googlemail.com
 executables: []
 
@@ -75,10 +75,10 @@ extensions: []
 extra_rdoc_files: 
 - readme.textile
 files: 
-- readme.textile
 - lib/asin.rb
-- test/test_helper.rb
 - test/test_asin.rb
+- test/test_helper.rb
+- readme.textile
 has_rdoc: true
 homepage: http://github.com/phoet/asin
 licenses: []
@@ -95,10 +95,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: 29
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 9
+      version: "1.9"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
@@ -114,7 +115,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Simple interface to Amazon Item lookup
+summary: Simple interface to Amazon Item lookup.
 test_files: 
-- test/test_helper.rb
 - test/test_asin.rb
+- test/test_helper.rb