recs4 0.0.1

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 kinumi
+
+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/Manifest.txt

@@ -0,0 +1,12 @@
+README.txt
+LICENSE.txt
+Manifest.txt
+Rakefile
+setup.rb
+lib/recs4.rb
+lib/recs4/operation.rb
+lib/recs4/version.rb
+lib/recs4/xml/element.rb
+lib/recs4/xml/elements.rb
+test/test_helper.rb
+test/jp_recs4_test.rb

data/README.txt

@@ -0,0 +1,47 @@
+== RECS4 is
+
+  An interface library to use 
+  the Amazon E-Commerce Service 4.0 (ECS4.0) API on Ruby.
+
+
+== Example to use
+
+  o = RECS4::Operation.new("Your AWSAccessKeyId", :locale => "jp")
+
+  # ItemLookup Operation
+  r = o.item_lookup("some asin", :response_group => "Large")
+  # Get element value
+  r[:items][:item][:asin].text #=> "some asin"
+  # Get attribute value
+  r[:items][:item][:item_attributes][:creator].a("Role") #=> "Artist"
+
+  # ItemSearch Operation
+  r = o.item_search("keywords")
+  # Get total pages
+  r[:items][:total_pages].text.to_i
+  # Get All items
+  r[:items][:item].each do |item|
+    item[:item_attributes][:artist].text
+  end
+
+
+== License
+  
+  See LICENSE
+
+
+== Report bugs
+  
+  https://rubyforge.org/projects/recs4/
+  
+
+== SVN repository
+
+  http://www.looselife.org/svn/ruby/lib/recs4/trunk/  
+
+
+== Developper
+
+  * kinumi
+  * kinumi@looselife.org
+  * http://www.looselife.org/

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'recs4', 'version')
+
+AUTHOR            = "kinumi"  # can also be an array of Authors
+EMAIL             = "kinumi@looselife.org"
+DESCRIPTION       = "An interface library to use the Amazon E-Commerce Service 4.0 (ECS4.0) API on Ruby."
+GEM_NAME          = "recs4" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "recs4" # The unix name for your project
+HOMEPATH          = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+RELEASE_TYPES     = %w( gem ) # can use: gem, tar, zip
+
+
+NAME  = "recs4"
+REV   = File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+# VERS  = ENV['VERSION'] || (RECS4::VERSION::STRING + (REV ? ".#{REV}" : ""))
+ENV['VERSION'] = (RECS4::VERSION::STRING + (REV ? ".#{REV}" : ""))
+VERS  = ENV['VERSION']
+CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = [
+  "--quiet", 
+  "--title", 
+  "recs4 documentation",
+  "--opname", 
+  "index.html",
+  "--line-numbers", 
+  "--main",
+  "README",
+  "--inline-source"
+]
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN #An array of file patterns to delete on clean.
+  
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end

data/lib/recs4.rb

@@ -0,0 +1,2 @@
+require "recs4/version"
+require "recs4/operation"

data/lib/recs4/operation.rb

@@ -0,0 +1,385 @@
+require "uri"
+require "open-uri"
+require "kconv"
+require "recs4/xml/element"
+
+module RECS4 #:nodoc:
+  LOCALES = [
+    "ca",
+    "de",
+    "fr",
+    "jp",
+    "uk",
+    "us",
+  ]
+  DEFAULT_LOCALE = "us"
+  
+  WS_URLS = {
+    "ca" => "http://webservices.amazon.ca/onca/xml?Service=AWSECommerceService",
+    "de" => "http://webservices.amazon.de/onca/xml?Service=AWSECommerceService",
+    "fr" => "http://webservices.amazon.fr/onca/xml?Service=AWSECommerceService",
+    "jp" => "http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService",
+    "uk" => "http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService",
+    "us" => "http://webservices.amazon.com/onca/xml?Service=AWSECommerceService",
+  }
+  
+  # All operations of ECS4.0
+  OPERATIONS = {
+    :browse_node_lookup       => "BrowseNodeLookup",
+    :cart_add                 => "CartAdd",
+    :cart_clear               => "CartClear",
+    :cart_create              => "CartCreate",
+    :cart_get                 => "CartGet",
+    :cart_modify              => "CartModify",
+    :customer_content_lookup  => "CustomerContentLookup",
+    :customer_content_search  => "CustomerContentSearch",
+    :help                     => "Help",
+    :item_lookup              => "ItemLookup",
+    :item_search              => "ItemSearch",
+    :list_lookup              => "ListLookup",
+    :list_search              => "ListSearch",
+    :seller_listing_lookup    => "SellerListingLookup",
+    :seller_listing_search    => "SellerListingSearch",
+    :seller_lookup            => "SellerLookup",
+    :similarity_lookup        => "SimilarityLookup",
+    :transaction_lookup       => "TransactionLookup",
+  }
+  
+  # Common parameters of all operations
+  GLOBAL_PARAMS = {
+    :locale                   => "Locale",
+    :associate_tag            => "AssociateTag",
+    :version                  => "Version",
+  }
+  
+  # Parameters of ItemLookup
+  ITEM_LOOKUP_PARAMS = {
+    :item_id                  => "ItemId", 
+    :id_type                  => "IdType", 
+    :search_index             => "SearchIndex", 
+    :merchant_id              => "MerchantId",
+    :condition                => "Condition", 
+    :delivery_method          => "DeliveryMethod", 
+    :ispu_postal_code         => "ISPUPostalCode", 
+    :offer_page               => "OfferPage", 
+    :review_page              => "ReviewPage", 
+    :variation_page           => "VariationPage",
+    :response_group           => "ResponseGroup",
+  }
+  
+  # Parameters of ItemSearch
+  ITEM_SEARCH_PARAMS = {
+    :availability             => "Availability",
+    :review_sort              => "ReviewSort",
+    :search_index             => "SearchIndex",
+    :keywords                 => "Keywords",
+    :title                    => "Title",
+    :power                    => "Power",
+    :browse_node              => "BrowseNode",
+    :artist                   => "Artist",
+    :author                   => "Author",
+    :actor                    => "Actor",
+    :director                 => "Director",
+    :audience_rating          => "AudienceRating",
+    :manufacturer             => "Manufacturer",
+    :music_label              => "MusicLabel",
+    :composer                 => "Composer",
+    :publisher                => "Publisher",
+    :brand                    => "Brand",
+    :conductor                => "Conductor",
+    :orchestra                => "Orchestra",
+    :text_stream              => "TextStream",
+    :item_page                => "ItemPage",
+    :sort                     => "Sort",
+    :city                     => "City",
+    :cuisine                  => "Cuisine",
+    :neighborhood             => "Neighborhood",
+    :minimum_price            => "MinimumPrice",
+    :maximum_price            => "MaximumPrice",
+    :merchantid               => "MerchantId",
+    :condition                => "Condition",
+    :delivery_method          => "DeliveryMethod",
+    :response_group           => "ResponseGroup",
+  }
+  
+  # Parameter of BrowseNodeLookup
+  BROWSE_NODE_LOOKUP_PARAMS = {
+    :browse_node_id           => "BrowseNodeId",
+    :response_group           => "ResponseGroup",
+  }
+  
+  # All parameters
+  ALL_PARAMS = {}
+  ALL_PARAMS.merge! GLOBAL_PARAMS
+  ALL_PARAMS.merge! ITEM_LOOKUP_PARAMS
+  ALL_PARAMS.merge! ITEM_SEARCH_PARAMS
+  ALL_PARAMS.merge! BROWSE_NODE_LOOKUP_PARAMS
+  
+  #
+  # This class wraps the Amazon ECS4.0 API
+  # 
+  # Using REST request internally.
+  # 
+  # Example to use:
+  #   
+  #   o = RECS4::Operation.new("Your AWSAccessKeyId", :locale => "jp")
+  #   
+  #   # ItemLookup Operation
+  #   r = o.item_lookup("some asin", :response_group => "Large")
+  #   # Get element value
+  #   r[:items][:item][:asin].text #=> "some asin"
+  #   # Get attribute value
+  #   r[:items][:item][:item_attributes][:creator].a("Role") #=> "Artist"
+  #   
+  #   # ItemSearch Operation
+  #   r = o.item_search("keywords")
+  #   # Get total pages
+  #   r[:items][:total_pages].text.to_i
+  #   # Get All items
+  #   r[:items][:item].each do |item|
+  #     item[:item_attributes][:artist].text
+  #   end
+  #   
+  class Operation
+    #
+    # Available options: Look RECS4::GLOBAL_PARAMS
+    #
+    # "Locale" parameter is required in ECS4.0 API.
+    # But :locale option can be skipped in RECS4.
+    # DEFAULT_LOCALE is used.
+    #
+    def initialize(aws_access_key_id, options = {})
+      @aws_access_key_id = aws_access_key_id
+      @options = {}
+      GLOBAL_PARAMS.each_key do |key|
+        @options[key] = options[key]
+      end
+      unless @options.keys.include?(:locale)
+        @options[:locale] = DEFAULT_LOCALE
+      end
+      @element_names = {}
+    end
+
+    #
+    # Available options: Look RECS4::ITEM_LOOKUP_PARAMS    
+    #    
+    def item_lookup(item_id, options = {})
+      unless has_valid_item_lookup_query(item_id, options)
+        return nil
+      end
+      url = item_lookup_url(item_id, options)
+      response_xml = get_response(url)
+      parsed_xml = REXML::Document.new(response_xml)
+      return RECS4::XML::Element.new(parsed_xml.root)
+    end
+    
+    #
+    # Available options: Look RECS4::ITEM_SEARCH_PARAMS
+    #
+    # "keywords" can be nil.
+    # If "keywords" is nil, other options for searching must not be nil.
+    # For example, :artist, :author, and so on.
+    #
+    def item_search(keywords, options = {})
+      unless options[:search_index]
+        options[:search_index] = "Blended"
+      end
+      unless has_valid_item_search_query(keywords, options)
+        return nil
+      end
+      url = item_search_url(keywords, options)
+      response_xml = get_response(url)
+      parsed_xml = REXML::Document.new(response_xml)
+      return RECS4::XML::Element.new(parsed_xml.root)
+    end
+    
+    #
+    # Available options: Look BROWSE_NODE_LOOKUP_PARAMS
+    #
+    def browse_node_lookup(browse_node_id, options = {})
+      unless has_valid_browse_node_lookup_query(browse_node_id, options)
+        return nil
+      end
+      url = browse_node_lookup_url(browse_node_id, options)
+      response_xml = get_response(url)
+      parsed_xml = REXML::Document.new(response_xml)
+      return RECS4::XML::Element.new(parsed_xml.root)
+    end
+
+    # Not implemented yet
+    def cart_add
+    end
+    # Not implemented yet
+    def cart_clear
+    end
+    # Not implemented yet
+    def cart_get
+    end
+    # Not implemented yet
+    def cart_modify
+    end
+    # Not implemented yet
+    def customer_controller_lookup
+    end
+    # Not implemented yet
+    def customer_controller_search
+    end
+    # Not implemented yet
+    def help
+    end
+    # Not implemented yet
+    def list_lookup
+    end
+    # Not implemented yet
+    def list_search
+    end
+    # Not implemented yet
+    def seller_listing_lookup
+    end
+    # Not implemented yet
+    def seller_listing_search
+    end
+    # Not implemented yet
+    def seller_lookup
+    end
+    # Not implemented yet
+    def similarity_lookup
+    end
+    # Not implemented yet
+    def transaction_lookup
+    end
+
+  private
+    #
+    # Get HTTP response
+    #
+    def get_response(url)
+      return open(url).read
+    end
+
+    #
+    # Generate a Operation URL
+    # 
+    def operation_url(operation, params = {})
+      url = WS_URLS[@options[:locale]].dup
+      url << "&AWSAccessKeyId=#{@aws_access_key_id}"
+      url << "&Operation=#{OPERATIONS[operation]}"
+      ALL_PARAMS.each_key do |key|
+        if params[key]
+          url << "&#{ALL_PARAMS[key]}=#{params[key]}"
+        end
+      end
+      return URI.escape(url.toutf8)
+    end
+
+    #
+    # Generate a ItemLookup operation URL
+    #
+    def item_lookup_url(item_id, options = {})
+      params = {
+        :item_id => item_id
+      }
+      GLOBAL_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end          
+      end
+      ITEM_LOOKUP_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end
+      end
+      return operation_url(:item_lookup, params)
+    end
+    
+    #
+    # Generate a ItemSearch operation URL
+    #
+    def item_search_url(keywords, options = {})
+      params = {}
+      if keywords
+        params[:keywords] = keywords
+      end
+      GLOBAL_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end          
+      end
+      ITEM_SEARCH_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end
+      end
+      return operation_url(:item_search, params)
+    end
+
+    #
+    # Generate a BrowseNodeLookup operation URL
+    #
+    def browse_node_lookup_url(browse_node_id, options = {})
+      params = {
+        :browse_node_id => browse_node_id
+      }
+      GLOBAL_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end          
+      end
+      BROWSE_NODE_LOOKUP_PARAMS.each_key do |key|
+        if options[key]
+          params[key] = options[key]
+        end
+      end
+      return operation_url(:browse_node_lookup, params)
+    end
+    
+    def has_valid_item_lookup_query(item_id, options ={})
+      # ItemId is required
+      unless item_id
+        return false
+      end
+      return true
+    end
+    
+    def has_valid_item_search_query(keywords, options = {})
+      # SearchIndex is required
+      unless options[:search_index]
+        return false
+      end
+      # At least one of the parameter to search      
+      search_word_enabled = nil
+      unless keywords
+        [
+          :title, 
+          :browse_node, 
+          :power, 
+          :artist, 
+          :author, 
+          :actor, 
+          :director, 
+          :manufacturer, 
+          :music_label, 
+          :composer, 
+          :publisher, 
+          :brand, 
+          :conductor, 
+          :orchestra
+        ].each do |key|
+          search_word_enabled ||= options[key]
+        end
+        unless search_word_enabled
+          return false
+        end
+      end
+      return true
+    end
+
+    def has_valid_browse_node_lookup_query(browse_node_id, options ={})
+      # BrowseNode is required
+      unless browse_node_id
+        return false
+      end
+      return true
+    end
+  end
+end