amazonian 0.1.0 → 0.2.0

data/.gitignore

@@ -3,3 +3,4 @@ pkg/*
 .bundle
 *.swp
 .*.swp
+.yardoc/*

data/README.rdoc

@@ -1,10 +1,7 @@
 == Status
-This project is in active development as of 2010-11.
-
-Currently it can be used as a rails plugin, and maybe as a gem (untested).
+This project is in active development as of 2010-12.
 
 == Installation
-
 Copy or symlink into your application's /lib folder.
 
 In your ApplicationController:
@@ -16,20 +13,31 @@ In your ApplicationController:
 Then create an initializer in config/initializers:
   require 'amazonian'
   Amazonian.setup do |config|
-    config.secret = 'ZkD9VorhnJjoPxZp8S/bP0K3G4NBQPNQrfU4OOUn'
-    config.key    = 'AKIAJCTUFLKJWEVW6XVQ'
-    #config.debug  = true
+    #Put your Amazon Web Services Key and Secret Key in here
+    config.secret = '<>'
+    config.key    = '<>'
+
+    # prints more debug info to the console. Default: false
+    # config.debug  = true
+
+    # the default default_search is :All, other tempting options: :Music, :GourmetFood, etc
+    config.default_search = :Music
+
+    # the gem will attempt to filter out duplicate requests.  Default: true
+    config.cache_last = true
   end
 
+
 == Usage
   Amazonian.asin "1430218150"
   #=> #<Amazonian::Item>
 
-  #soon:
   Amazonian.search "The art of Computer Programming"  #Title
   Amazonian.search "978-0201853926"                   #ISBN-13
   Amazonian.search "0201853922"                       #ISBN-10
   Amazonian.search "<whateveryouwant>"                #Anything you might put in the search box on Amazon.com.
+  #=> #<Amazonian::Search>
+
 
 == Info
 

data/lib/amazonian.rb

@@ -2,48 +2,84 @@ require 'patron'
 require 'crack'
 require 'hashie'
 
+#
+# This module is designed to allow easier querying of the Amazon Product Advertising API
+# from within your Ruby or Rails applications.
+#
+# Basic usage requires first calling +Amazonian.setup+ to provide your Amazon AWS Key and
+# Secret key for the module to use in querying the database.
+#
+# Amazons internal product ids can be used to retrieve data from the API with +Amazonian.asin+.
+#
+# Searching for products is done via +Amazonian.search+
+#
+# @author Robert L. Carpenter (Modern codebase, interface, gem-ability)
+# @author phoet (Original ASIN interface and implementation of Request Signing, etc.) https://github.com/phoet/asin
+#
+# @api Amazon Web Services Product Advertising API
+#
+# @version 0.2.0
+#
 module Amazonian
+
   #worker objects
   @@digest = OpenSSL::Digest::Digest.new('sha256')
   @@logger = Logger.new(STDERR)
   @@patron = Patron::Session.new
 
   #hold the most recent request/response
-  @@request  = nil
-  @@response = nil
-  @@query    = nil
+  @request  = nil
+  @response = nil
+  @query    = nil
 
   #configuration variables
-  @@host   = 'webservices.amazon.com'
-  @@path   = '/onca/xml'
-  @@debug  = true
-  @@key    = ''
-  @@secret = ''
+  @host           = 'webservices.amazon.com'
+  @path           = '/onca/xml'
+  @debug          = true
+  @key            = ''
+  @secret         = ''
+  @default_search = :All
+  @cache_last     = true
 
   mattr_reader   :host,:path,:response,:request
-  mattr_accessor :key,:secret,:debug
+  mattr_accessor :key,:secret,:debug,:default_search,:cache_last
 
   #Configure Patron
   @@patron.timeout = 10
 
+  #
   # Configure the basic request parameters for Amazonian.
+  #
+  # Pass in a block with 1 parameter and modify configuration
+  # variables from there.
+  #
+  # @yield [amazonian] Configuration code block.
+  #
+  # @example
+  #     require 'Amazonian'
+  #     Amazonian.setup do |ama|
+  #       ama.key            = "my awesome key for AWS"
+  #       ama.secret         = "super secret secret key for AWS"
+  #       ama.debug          = true
+  #       ama.default_search = :Music
+  #       ama.cache_last     = false
+  #     end
+  #
   def self.setup
     yield self if block_given?
   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)"
+  # Perform an ASIN (Amazon Standard Identification Number) lookup.
   #
-  # ==== Options:
+  # @param [String] The ASIN with which to query the API.
+  # @param [Hash] Additional options to be passed to the API.
+  # @option params [Symbol] :Operation defaults to :ItemLookup
+  # @option params [Symbol] :ItemLookup defaults to the ASIN passed as param 1.
   #
-  # Additional parameters for the API call like this:
+  # @see For more information on the parameters the API accepts, see http://docs.amazonwebservices.com/AWSEcommerceService/4-0/
   #
-  #   lookup(asin, :ResponseGroup => :Medium)
+  # @return [Amazonian::Item] Representing the response from the API
   #
   def self.asin(asin, params={})
     params = params.merge :Operation => :ItemLookup, :ItemId => asin
@@ -51,61 +87,87 @@ module Amazonian
     Item.new xml['ItemLookupResponse']['Items']['Item']
   end
 
+  #
+  # Perform a search query to the API.  This is basically the same thing as
+  # searching with the Amazon website.
+  #
+  # @param [String] The search query
+  # @param [Hash] Additional options to be passed to the API
+  # @option params [Symbol] :Operation defaults to :ItemSearch
+  # @option params [Symbol] :Keywords defaults to the passed search query
+  #
+  # @see For more information on the parameters the API accepts, see http://docs.amazonwebservices.com/AWSEcommerceService/4-0/
+  #
+  # @return [Amazonian::Search] Representing the response from the API.  Items returned by the search query are represented as 
+  #   +Amazonian::Item+ inside +Amazonian::Search+
+  #
   def self.search(query, params={})
     params = params.merge :Operation => :ItemSearch,
                           :Keywords => query
 
-    params[:SearchIndex] = :Music if params[:SearchIndex].nil?
+    params[:SearchIndex] = @default_search if params[:SearchIndex].nil?
 
     xml = self.call params
     Search.new xml['ItemSearchResponse']
   end
 
-  #private
+  private
 
+  #
+  # Director function. Builds out the Request, Signs it, Sends it off, and Parses its XML all via small helper functions.
+  #
+  # @param params [Hash] All of the parameters to be formatted into the API REST call.
+  # @return [Crack::XML] The Parsed XML
+  #
   def self.call(params)
-    raise "Cannot call the Amazon API without key and secret key." if @@key.blank? || @@secret.blank?
+    raise "Cannot call the Amazon API without key and secret key." if @key.blank? || @secret.blank?
 
     #get the signed query, and assemble the querystring
-    log :debug, "Started Amazonian request for params: #{params.map {|p| "#{p[0]}=>#{p[1]}" }.join ','}"  if @@debug
+    log :debug, "Started Amazonian request for params: #{params.map {|p| "#{p[0]}=>#{p[1]}" }.join ','}"  if @debug
 
     #memoize the last request for faster API querying...
     query = assemble_querystring params
-    if query == @@query
+    if @cache_last && query == @query && @response.body
       log :debug, "MEMO'D! Shortcutting API call for dup request."
-      return Crack::XML.parse @@response.body
+      return Crack::XML.parse @response.body
     end
-    @@query = query
+    @query = query
 
     #sign the query
     signed = sign_query query
 
     #assemble the full URL
-    @@request = "http://#{@@host}#{@@path}?#{signed}"
+    @request = "http://#{@host}#{@path}?#{signed}"
 
     #make the call
-    log :info, "performing rest call to '#{@@request}'" if @@debug
-    @@response = @@patron.get @@request
+    log :info, "performing rest call to '#{@request}'" if @debug
+    @response = @@patron.get @request
 
-    log :debug, "Response Code: #{@@response.status}" if @@debug
+    log :debug, "Response Code: #{@response.status}" if @debug
 
     #todo, this memo logic is broken....an error code is not always without a body
-    log :error, "Amazon API Error: #{@@response.status}" if @@response.status >= 400
+    log :error, "Amazon API Error: #{@response.status}" if @response.status >= 400
 
     #parse the response and return it
-    Crack::XML.parse @@response.body
+    Crack::XML.parse @response.body
   end
 
+  #
+  # Builds out a Query String from a hash of symbols.
+  #
   def self.assemble_querystring(params)
     # Nice tutorial http://cloudcarpenters.com/blog/amazon_products_api_request_signing/
     params[:Service] = :AWSECommerceService
-    params[:AWSAccessKeyId] = @@key
+    params[:AWSAccessKeyId] = @key
 
     # CGI escape each param
     # signing needs to order the query alphabetically
     params.map{|key, value| "#{key}=#{CGI.escape(value.to_s)}" }.sort.join('&').gsub('+','%20')
   end
 
+  #
+  # Signs a query string
+  #
   def self.sign_query(query)
     #make a copy... fixme fixme I'm awkward
     q = query.clone
@@ -114,27 +176,30 @@ module Amazonian
 
     # Sign the entire get-request (not just the querystring)
     # possible gotcha if Patron starts using more/different headers.
-    request_to_sign = "GET\n#{@@host}\n#{@@path}\n#{q}"
+    request_to_sign = "GET\n#{@host}\n#{@path}\n#{q}"
 
     "#{q}&Signature=#{sign_request request_to_sign}"
   end
 
+  #
+  # Signs an entire request string
+  #
   def self.sign_request(request_to_sign)
     # Sign it.
-    hmac = OpenSSL::HMAC.digest(@@digest, @@secret, request_to_sign)
+    hmac = OpenSSL::HMAC.digest(@digest, @secret, request_to_sign)
 
     # Don't forget to remove the newline from base64
     CGI.escape(Base64.encode64(hmac).chomp)
   end
 
   def self.log(severity, message)
-    @@logger.send severity, message if @@logger
+    @logger.send severity, message if @logger
   end
 
 
   # =Item
   #
-  # The +Item+ class is a wrapper for the Amazon XML-REST-Response.
+  # The +Item+ class is used to neatly box up the Amazon REST API responses into an Object.
   #
   # A Hashie::Mash is used for the internal data representation and can be accessed over the +raw+ attribute.
   #
@@ -145,16 +210,36 @@ module Amazonian
     end
 
     def title
-      @raw.ItemAttributes.Title
+      if @raw.ItemAttributes && @raw.ItemAttributes.Title
+        @raw.ItemAttributes.Title
+      else
+        nil
+      end
     end
   end
 
+  # =Search
+  # The +Search+ class is used to neatly box up the Amazon REST API responses into Objects.
+  #
+  # When using Amazonian.search you should receive an Search object.  Search also attempts
+  # to autoboxe all of the Items returned in the search results into an array of +Amazonian::Item+
+  # objects.
+  #
+  # A Hashie::Mash is used for the internal data representation and can be accessed over the +raw+ attribute.
+  #
   class Search
     attr_reader :items
     def initialize(hash)
       @raw = Hashie::Mash.new(hash)
       @items = []
-      @raw.Items.Item.each {|i| @items.push Amazonian::Item.new(i) }
+
+      if @raw.Items && @raw.Items.Item
+        if @raw.Items.TotalResults.to_i > 1
+          @raw.Items.Item.each {|i| @items.push Amazonian::Item.new(i) }
+        else
+          @items.push Amazonian::Item.new(@raw.Items.Item)
+        end
+      end
     end
   end
 

data/lib/amazonian/version.rb

@@ -1,3 +1,3 @@
 module Amazonian
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: amazonian
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Robert L. Carpenter
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-29 00:00:00 -07:00
+date: 2010-12-05 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency