ECS 0.1.0

data/CHANGELOG

@@ -0,0 +1,7 @@
+0.1.0
+* Initial release
+* Forces ECS API version 2007-01-17
+* Requires libxml-ruby (tested with libxml-ruby-0.3.8.4)
+* The XML returned from ECS, when parsed into an XML::Document or XML::Node object (libxml-ruby-0.3.8.4)
+	breaks the find() method on both classes.  If I strip the namespace, it works.
+	ECS.strip_namespace? governs this behavior.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Zachary Holt
+
+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/README

@@ -0,0 +1,3 @@
+Please see the MIT-LICENSE file for copyright and distribution information.
+
+ECS is a Ruby interface to Amazon's E-Commerce Service.

data/lib/ecs.rb

@@ -0,0 +1,268 @@
+#!/usr/local/bin/ruby
+
+dir = File::dirname( __FILE__ )
+
+require 'rubygems'
+require 'xml/libxml'
+require 'digest/md5'
+require 'net/http'
+require 'erb'
+
+module ECS
+  Dir[File.join( File.dirname( __FILE__ ), "*.rb" )].each { |f| require f }
+
+  require File.join( File.dirname( __FILE__ ), 'ecs', 'operations' )
+  require File.join( File.dirname( __FILE__ ), 'ecs', 'response_groups' )
+  require File.join( File.dirname( __FILE__ ), 'ecs', 'help' )
+  require File.join( File.dirname( __FILE__ ), 'ecs', 'help_response_group' )
+  require File.join( File.dirname( __FILE__ ), 'ecs', 'time_management' )
+
+#  [ 'help', 'help_response_group', 'operations', 'response_groups', 'time_management' ].each { |f| require( File.join( File.dirname( __FILE__ ), 'ecs', f ) ) }
+#  Dir[File.join( File.join( File.dirname( __FILE__ ), 'ecs' ), "*.rb" )].each { |f| require f }
+#  Dir[File.join( File.join( File.dirname( __FILE__ ), 'ecs', 'operation' ), "*.rb" )].each { |f| require f }
+#  Dir[File.join( File.join( File.dirname( __FILE__ ), 'ecs', 'response_group' ), "*.rb" )].each { |f| require f }
+
+  @@associate_id = 'limn-20'
+  @@access_key_id = ''
+  @@default_default_locale = :us
+  @@default_locale = @@default_default_locale
+  @@cache_directory = ''
+  @@cache = true
+  @@cache_suffix = 'ecs_cache'
+
+  # libxml-ruby is not able to do XML::Document#find or XML::Node#find with xml returned from Amazon.
+  # If you remove the namespace from the xml, it works perfectly
+  @@strip_namespace = true
+  
+  def self.method_missing( meth, *args )
+    meth_s = meth.to_s
+    begin
+      klass_name = meth_s.camel_case
+      instance = nil
+      if meth_s =~ /^(.*)_response_group$/
+        instance = self.resolve_response_group_klass( klass_name )
+      else
+        klass = self.resolve_operation_klass( klass_name )
+
+#        string_to_eval = "#{klass_name}.new"
+#        puts "Now going to #{string_to_eval}"
+        instance = klass.new
+#        instance = instance_eval( string_to_eval, __FILE__, __LINE__ )
+        instance.parameters = *args
+        instance.parameters = {} unless instance.parameters.is_a?( Hash )
+
+        # If no ResponsGroup is set, then allow the defaults
+        unless instance.parameters[:ResponseGroup].nil?
+          # Otherwise, be sure :Request is included
+          instance.parameters[:ResponseGroup] = [instance.parameters[:ResponseGroup]] unless instance.parameters[:ResponseGroup].is_a?( Array )
+          instance.parameters[:ResponseGroup] << :Request unless instance.parameters[:ResponseGroup].include?( :Request ) || instance.parameters[:ResponseGroup].include?( 'Request' )
+        end
+      end
+      instance
+    rescue NameError => e
+      raise NameError, "#{e.message}"#Are you sure that ECS::#{klass_name} is defined?"
+    end
+  end
+
+
+  def self.associate_id
+    @@associate_id
+  end
+  def self.associate_id=( k )
+    @@associate_id = k.to_s
+  end
+  def self.access_key_id
+    @@access_key_id
+  end
+  def self.access_key_id=( i )
+    @@access_key_id = i.to_s
+  end
+  
+  def self.default_locale
+    @@default_locale
+  end
+  def self.default_locale=( loc )
+    @@default_locale = self.resolve_locale( loc )
+  end
+  def self.reset_default_locale
+    @@default_locale = @@default_default_locale
+  end
+
+  def self.cache_directory
+    @@cache_directory
+  end
+  def self.cache_directory=( d='' )
+    directory = File.expand_path( d )
+    Dir.mkdir( directory ) unless File.exist?( directory )
+    raise( EACCESS, "#{directory} is not a suitable cache directory" ) unless File.writable?( directory ) && File.directory?( directory )
+    @@cache_directory = directory
+  end
+
+
+  def self.available_locales
+    [ :ca, :de, :fr, :jp, :uk, :us ]
+  end
+
+  def self.base_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'
+    }
+  end
+
+
+  def self.api_version
+    '2007-02-22'
+  end
+
+  def self.strip_namespace?
+    @@strip_namespace != false
+  end
+  def self.strip_namespace=( s )
+    @@strip_namespace = s != false
+  end
+
+  def self.call_web_service( p={} )
+    parameters = p.is_a?( Hash ) ? p : {}
+
+    locale = self.resolve_locale( parameters[:locale] )
+    parameters.delete( :locale )
+
+    sleep( ECS::TimeManagement.sleep_duration )
+    url = "#{ self.base_urls[locale] }&AWSAccessKeyId=#{self.access_key_id}&Version=#{self.api_version}&AssociateTag=#{self.associate_id}&#{ parameters.keys.map{ |k| "#{ERB::Util.url_encode( k.to_s ) }=#{ERB::Util.url_encode( parameters[k].is_a?( Array ) ? parameters[k].join( ',' ) : parameters[k].to_s )}" }.join( '&' ) }"
+    #puts url
+    r = Net::HTTP.get_response( URI.parse( url ) )
+    r.value # this will raise an error if there was one.
+    @@strip_namespace && r.body =~ /(.*)xmlns\s*=\s*".*?"(.*)/m ? "#{$1}#{$2}" : r.body
+  end
+  
+  def self.resolve_locale( l=nil )
+    !l.nil? && self.available_locales.include?( l.to_s.downcase.to_sym ) ? l.to_s.downcase.to_sym : self.default_locale
+  end
+
+  def self.resolve_response_group_klass( name='' )
+    klass_name = ECS::HelpResponseGroup.resolve_response_group_name( name )
+    klass = ECS::ResponseGroups[klass_name]
+    if klass.nil?
+      string_to_eval = "class #{klass_name} < HelpResponseGroup
+                          @@response_group_name=nil
+                          @@valid_operations=nil
+                          @@elements=nil
+                          @@help_xml=nil
+                          ECS::ResponseGroups['#{klass_name}'] = self
+                        end
+                        #{klass_name}"
+      #puts string_to_eval
+      klass = instance_eval( string_to_eval, __FILE__, __LINE__ )
+    end
+    klass
+  end
+  def self.resolve_operation_klass( name='' )
+      klass_name = ECS::Help.resolve_operation_name( name )
+      klass = ECS::Operations[klass_name]
+      if klass.nil?
+        string_to_eval = "class #{klass_name} < Help
+                            @@operation_name=nil
+                            @@help_xml=nil
+                            @@required_parameters=nil
+                            @@available_parameters=nil
+                            @@default_response_groups=nil
+                            @@available_response_groups=nil
+                            ECS::Operations['#{klass_name}'] = self
+                          end
+                          #{klass_name}"
+#          puts string_to_eval
+        klass = instance_eval( string_to_eval, __FILE__, __LINE__ )
+      end
+      klass
+  end
+  
+  def self.xml_for_parameters( parameters={}, force=false )
+    # if you pass a block to this method, the XML::Document object
+    # will be yielded (if it's not cached) and you will be able to return
+    # true to cache it or false to not cache it.  The object is yielded
+    # regardless of the value of ECS.cache?
+    # In other words, ECS.cache? is respected only when there is no block
+    tag = self.resolve_cache_tag( parameters )
+    xml = nil
+
+    xml = self.read_cache( tag ) unless force
+
+    if xml.nil?
+      xml = self.call_web_service( parameters )
+      parser = XML::Parser.new
+      parser.string = xml
+      xml = parser.parse
+      we_should_cache = block_given? ? yield( xml ) : self.cache?
+      self.write_cache( tag, xml.to_s ) if we_should_cache
+    end
+    
+    xml
+  end
+
+  def self.read_cache( tag_or_parameters )
+    tag = tag_or_parameters.is_a?( String ) ? tag_or_parameters : self.resolve_cache_tag( tag_or_parameters )
+    XML::Document.file( tag ) if File.exist?( tag )
+  end
+  def self.write_cache( tag_or_parameters, content )
+    tag = tag_or_parameters.is_a?( String ) ? tag_or_parameters : self.resolve_cache_tag( tag_or_parameters )
+    File.open( tag, 'w' ) { |f| f << content }
+  end
+
+  def self.clear_cache( tag=nil )
+    if tag.nil?
+      Dir[File.join( self.cache_directory, "*.#{@@cache_suffix}" )].each { |f| File.unlink( f ) }
+    else
+      File.unlink( tag )
+    end
+  end
+
+  def self.cache?
+    @@cache != false
+  end
+  def self.cache=( true_or_false=true )
+    @@cache = true_or_false != false
+  end
+  
+  def self.cached?( p={} )
+    File.exist?( p.is_a?( String ) ? p : self.resolve_cache_tag( p ) )
+  end
+  
+  
+  def self.query_string( p={} )
+    ( p.is_a?( Hash ) ? p : {} ).keys.map{ |k| k.to_s }.sort.map{ |k| "#{k}=#{p[k.to_sym]}" }.join( '&' )
+  end
+  
+  def self.resolve_cache_tag( p={} )
+    "#{cache_directory}/#{Digest::MD5.hexdigest( p.is_a?( String ) ? p : query_string( p ) )}.#{@@cache_suffix}"
+  end
+end
+
+##At this point I can do
+##  
+##b = ECS.browse_node_lookup( :BrowseNodeId => 43242 )
+##
+##and b is an object of class ECS::BrowseNodeLookup
+##
+##
+##What I would like to be able to do is say
+##  
+##1) b.results (or some such)
+##
+##and get either one ECS::BroseNodeInfo (which include ECS::ResponseGroup) object
+##or an array of ECS::BrowseNodeInfo objects
+##
+##
+##This should happen by
+##
+##2) Checking a @results instance variable
+##
+##3) If @results is null, parse and iterate over the xml, creating a ECS::BrowseNodeInfo object for each <BrowseNodeInfo> element
+##
+##4) If the xml is null, check the disk to see whether there is a cached version
+##
+##5) If there is no cached version, call the web service and get the xml, caching it when you are done with it

data/lib/ecs/help.rb

@@ -0,0 +1,282 @@
+#!/usr/local/bin/ruby
+
+module ECS
+  class Help
+    instance_variable_set( '@operation_name', nil )
+    instance_variable_set( '@help_xml', nil )
+    instance_variable_set( '@required_parameters', nil )
+    instance_variable_set( '@available_parameters', nil )
+    instance_variable_set( '@default_response_groups', nil )
+    instance_variable_set( '@available_response_groups', nil )
+
+
+    @@help_map = {
+      :required_parameters => { :call_path => 'HelpResponse.Information.OperationInformation.RequiredParameters.Parameter' },
+      :available_parameters => { :call_path => 'HelpResponse.Information.OperationInformation.AvailableParameters.Parameter' },
+      :default_response_groups => { :call_path => 'HelpResponse.Information.OperationInformation.DefaultResponseGroups.ResponseGroup' },
+      :available_response_groups => { :call_path => 'HelpResponse.Information.OperationInformation.AvailableResponseGroups.ResponseGroup' }
+    }
+
+    attr_accessor :parameters, :xml
+    ECS::Operations['Help'] = self
+
+    def self.operation_name
+      @operation_name ||= self.resolve_operation_name( self.name )
+    end
+    def self.help_xml( force=false )
+      if force || @help_xml.nil?
+        @help_xml = ECS.help( :HelpType => 'Operation', :About => self.operation_name ) { |x| ECS::Help.valid_aws_response( x ) }.xml
+      end
+      @help_xml
+    end
+
+
+    def self.valid_aws_response?( x )
+      xml = x
+      unless x.is_a?( XML::Document )
+        p = XML::Parser.new
+        p.string = x
+        xml = p.parse
+      end
+      
+      if self.errors_from_aws( xml ).empty?
+        n = xml.find( '//Request/IsValid' ).first
+        n.nil? || n.content.downcase != 'false'
+      else
+        false
+      end
+    end
+
+    def self.errors_from_aws( x )
+      xml = x
+      unless x.is_a?( XML::Document )
+        p = XML::Parser.new
+        p.string = x
+        xml = p.parse
+      end
+
+      errors = []
+      xml.find( '//Errors/Error' ).each do |error_node|
+        begin
+          m = error_node.Message.content
+          c = error_node.Code.content.gsub( /[\.:\s,\-_]/, '' )
+          errors << RuntimeError.new( m )
+        rescue Exception => e
+        end
+      end
+      errors
+    end
+
+
+    def self.required_parameters( force=false )
+      if force || @required_parameters.nil?
+        @required_parameters = []
+        self.help_xml.HelpResponse.Information.OperationInformation.RequiredParameters.Parameter.each do |p|
+          @required_parameters << p.content.to_s.to_sym
+        end
+      end
+      @required_parameters
+    rescue
+      []
+    end
+    def self.available_parameters( force=false )
+      if force || @available_parameters.nil?
+        @available_parameters = []
+        self.help_xml.HelpResponse.Information.OperationInformation.AvailableParameters.Parameter.each do |p|
+          @available_parameters << p.content.to_s.to_sym
+        end
+      end
+      @available_parameters
+    end
+    def self.optional_parameters( force=false )
+      self.available_parameters( force )
+    end
+
+    def self.default_response_groups( force=false )
+      if force || @default_response_groups.nil?
+        @default_response_groups = []
+        self.help_xml.HelpResponse.Information.OperationInformation.DefaultResponseGroups.ResponseGroup.each do |p|
+          @default_response_groups << ECS.resolve_response_group_klass( "#{p.content.to_s}ResponseGroup" )
+        end
+      end
+      @default_response_groups
+    end
+    def self.available_response_groups( force=false )
+      if force || @available_response_groups.nil?
+        @available_response_groups = []
+        self.help_xml.HelpResponse.Information.OperationInformation.AvailableResponseGroups.ResponseGroup.each do |p|
+          @available_response_groups << ECS.resolve_response_group_klass( "#{p.content.to_s}ResponseGroup" )
+        end
+      end
+      @available_response_groups
+    end
+
+
+    def self.resolve_operation_name( t )
+      t =~ /::([^:]*)$/ ? $1 : t
+    end
+
+    def operation_name
+      self.class.operation_name
+    end
+
+    def help_xml( force=false )
+      self.class.help_xml( force )
+    end
+    
+    def xml( force=false )
+      if force || @xml.nil?
+        self.class.required_parameters.each do |p|
+          raise(
+            ArgumentError,
+            "#{p} is a required parameter for the #{ self.operation_name } operation"
+          ) if !self.parameters.keys.include?( p.to_sym ) || self.parameters[p.to_sym].to_s.empty?
+        end
+
+        # Cache the xml only if it's a valid AWS Response
+        @xml = ECS.xml_for_parameters( self.parameters_for_xml ) { |x| ECS::Help.valid_aws_response?( x ) }
+      end
+      @xml
+    end
+    
+    def parameters_for_xml
+      self.parameters.merge( :Operation => self.operation_name )
+    end
+
+    def cached?
+      ECS.cached?( self.parameters_for_xml )
+    end
+
+    def cached_content
+      ECS.read_cache( self.parameters_for_xml )
+    end
+
+    def headers( force=false )
+      if force || @headers.nil?
+        @headers = {}
+        self.xml.find( '//OperationRequest/HTTPHeaders/Header' ).each do |header|
+          name = ''
+          value = ''
+          header.each_attr do |attribute|
+            name = attribute.value.to_sym if attribute.name == 'Name'
+            value = attribute.value if attribute.name == 'Value'
+          end
+          @headers[name] = value
+        end
+      end
+      @headers
+    rescue
+      @headers = []
+    end
+
+    def request_id( force=false )
+      if force || @request_id.nil?
+        @request_id = self.xml.find( '//OperationRequest/RequestId' ).first.content
+      end
+      @request_id
+    rescue
+      @request_id = 'Could not determine request_id'
+    end
+
+    def arguments( force=false )
+      if force || @arguments.nil?
+        @arguments = {}
+        self.xml.find( '//OperationRequest/Arguments/Argument' ).each do |argument|
+          name = ''
+          value = ''
+          argument.each_attr do |attribute|
+            name = attribute.value.to_sym if attribute.name == 'Name'
+            value = attribute.value if attribute.name == 'Value'
+          end
+          @arguments[name] = value
+        end
+      end
+      @arguments
+    rescue
+      @arguments = {}
+    end
+
+    def request_processing_time( force=false )
+      if force || @request_processing_time.nil?
+        @request_processing_time = self.xml.find( '//OperationRequest/RequestProcessingTime' ).first.content.to_f
+      end
+      @request_processing_time
+    rescue
+      @request_processing_time = -1.0
+    end
+    
+    def response_groups( force=false )
+      #these are the response groups that are included in this instance,
+      #not all those available to the class
+      if force || @response_groups.nil?
+        @response_groups = []
+
+        response_group_names = self.arguments[:ResponseGroup]
+
+        if response_group_names.nil?
+          @response_groups = self.class.default_response_groups
+        else
+          response_group_names.split( ',' ).each do |response_group_name|
+            @response_groups << ECS.resolve_response_group_klass( "#{response_group_name}ResponseGroup" )
+          end
+        end
+      end
+      @response_groups
+    end
+    
+    def potential_elements( force=false )
+      if force || @potential_elements.nil?
+        @potential_elements = []
+        self.response_groups.each do |response_group|
+          @potential_elements << response_group.elements
+        end
+        @potential_elements.flatten!.uniq!
+      end
+      @potential_elements
+    end
+
+    def errors( force=false )
+      @errors = self.class.errors_from_aws( self.xml ) if force || @errors.nil?
+      @errors
+    end
+    
+    def valid?( force=false )
+      @valid = self.class.valid_aws_response?( self.xml ) if force || @valid.nil?
+      @valid
+    end
+    
+    
+    def method_missing( meth, *args )
+      method_name = meth.to_s
+
+      # Note that if there is an element in the xml called each_*,
+      # in order to get to it, you can't pass a block
+      if method_name =~ /^each_(.*)$/ && block_given?
+        x = self.send( $1.to_sym, *args )
+        if [ Array, XML::Node::Set].include?( x.class )
+          x.each { |y| yield( y ) }
+        else
+          yield( x )
+        end
+      elsif method_name =~ /^(.*)_count$/
+        # Note that this will return the count for all descendants
+        # Not just children
+        x = self.send( $1.to_sym, *args )
+        x.respond_to?( :size ) ? x.size : 1
+      else
+        instance_variable_name = "@#{method_name}_var"
+        self.instance_eval( "
+          def #{method_name}( force=false )
+            if force || #{instance_variable_name}.nil?
+              #{instance_variable_name} = self.xml.find( '//#{method_name}' )
+              #{instance_variable_name} = #{instance_variable_name}.first if #{instance_variable_name}.size == 1
+            end
+            #{instance_variable_name}
+          end
+        " )
+      
+        self.send( meth, *args )
+      end
+    end
+  end
+end