vacuum 0.1.3 → 0.2.0.pre

data/README.md

@@ -2,42 +2,84 @@
 
 [![travis] [1]] [2]
 
-![vacuum] [3]
+Vacuum is a Ruby wrapper to [various Amazon Web Services (AWS) APIs] [3].
 
-Vacuum is a minimal Ruby wrapper to the [Amazon Product Advertising API] [4].
+![vacuum] [4]
 
-# Usage
+## Amazon Product Advertising API
+
+Vacuum knows the [Amazon Product Advertising API] [5] [inside out] [6].
 
 ```ruby
-require 'vacuum'
-
-# Create a request.
-req = Vacuum.new key:    'key',
-                 secret: 'secret',
-                 tag:    'tag',
-                 locale: 'us'
-
-# Build query.
-req.build 'Operation'   => 'ItemSearch',
-          'SearchIndex' => 'All',
-          'Keywords'    => 'Gilles Deleuze'
-
-# Execute.
-res = request.get
-
-# Consume response.
-if res.valid?
-  # res.to_hash
-  res.find('Item') do |item|
+request = Vacuum.new(:product_advertising) do |config|
+  config.locale 'US'
+
+  config.key    'key'
+  config.secret 'secret'
+  config.tag    'tag'
+end
+
+# Use an alternative Faraday adapter.
+# request.connection do |builder|
+#   builder.adapter :typhoeus
+# end
+
+# A barebone search request.
+request.build operation:    'ItemSearch',
+              search_index: 'Books',
+              keywords:     'Deleuze'
+response = request.get
+
+# A less verbose search.
+request.search :books, 'Deleuze'
+
+if response.valid?
+  # response.code
+  # response.body
+  # response.errors
+  # response.xml # The Nokogiri XML doc
+  # response.to_hash
+  response.find('Item') do |item|
     p item['ASIN']
   end
 end
 ```
+## Amazon Marketplace Web Services API
+
+The wrapper to the [Amazon Marketplace Web Services API] [7] is a
+work-in-progress.
+
+```ruby
+request = Vacuum.new(:mws_products) do |config|
+  config.locale      'US'
+
+  config.key         'key'
+  config.secret      'secret'
+  config.marketplace 'marketplace'
+  config.seller      'seller'
+end
+
+request.build 'Action'          => 'GetLowestOfferListingsForASIN',
+              'ASINList.ASIN.1' => '0231081596'
+offers = request.get.find 'GetLowestOfferListingsForASINResult'
+```
+
+## Other AWS APIs
+
+Vacuum should work with EC2, S3, IAM, SimpleDB, SQS, SNS, SES, ELB, CW, and so
+on. Implement and send a pull request.
+
+# Addendum
+
+![vacuums] [8]
 
-Read further [here] [5].
+> Workers queuing to crawl AWS.
 
 [1]: https://secure.travis-ci.org/hakanensari/vacuum.png
 [2]: http://travis-ci.org/hakanensari/vacuum
-[3]: http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png
-[4]: https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html
-[5]: https://github.com/hakanensari/vacuum/blob/master/examples/
+[3]: http://aws.amazon.com/
+[4]: http://f.cl.ly/items/2k2X0e2u0G3k1c260D2u/vacuum.png
+[5]: https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html
+[6]: https://github.com/hakanensari/vacuum/blob/master/examples/product_advertising/
+[7]: https://developer.amazonservices.com/gp/mws/docs.html
+[8]: http://f.cl.ly/items/1Q3W372A0H3M0w2H1e0W/hoover.jpeg

data/lib/vacuum/endpoint/base.rb

@@ -0,0 +1,58 @@
+module Vacuum
+  module Endpoint
+    # An Amazon Web Services (AWS) API endpoint.
+    class Base
+      LOCALES = %w(CA CN DE ES FR IT JP UK US)
+
+      # Raises a Not Implemented Error.
+      #
+      # When implemented, this should return a String AWS API host.
+      def host
+        raise NotImplementedError
+      end
+
+      # Returns the String AWS access key ID.
+      #
+      # Raises a Missing Key error if key is missing.
+      def key
+        @key or raise MissingKey
+      end
+
+      # Sets the String AWS access key ID.
+      attr_writer :key
+
+      # Returns the String AWS API locale (default: US).
+      #
+      # Raises a Bad Locale error if locale is not valid.
+      def locale
+        @locale ||= 'US'
+        LOCALES.include? @locale or raise BadLocale
+
+        @locale
+      end
+
+      # Sets the String AWS API locale.
+      attr_writer :locale
+
+      # Returns the String AWS access secret key.
+      #
+      # Raises a Missing Secret error if secret is missing.
+      def secret
+        @secret or raise MissingSecret
+      end
+
+      # Sets the String AWS access secret key.
+      attr_writer :secret
+
+      # Returns a String user agent for the AWS API request.
+      def user_agent
+        engine   = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
+        language = [engine, RUBY_VERSION, "p#{RUBY_PATCHLEVEL}"].join ' '
+        hostname = `hostname`.chomp
+        version  = Vacuum::VERSION
+
+        "Vacuum/#{version} (Language=#{language}; Host=#{hostname})"
+      end
+    end
+  end
+end

data/lib/vacuum/endpoint/mws.rb

@@ -0,0 +1,59 @@
+module Vacuum
+  module Endpoint
+    # A Marketplace Web Services (MWS) API endpoint.
+    class MWS < Base
+      # A list of MWS API hosts.
+      HOSTS = {
+        'CA' => 'mws.amazonservices.ca',
+        'CN' => 'mws.amazonservices.com.cn',
+        'DE' => 'mws-eu.amazonservices.com',
+        'ES' => 'mws-eu.amazonservices.com',
+        'FR' => 'mws-eu.amazonservices.com',
+        'IT' => 'mws-eu.amazonservices.com',
+        'JP' => 'mws.amazonservices.jp',
+        'UK' => 'mws-eu.amazonservices.com',
+        'US' => 'mws.amazonservices.com'
+      }
+
+      # Internal: Gets/Sets the Symbol MWS API type.
+      attr_accessor :api
+
+      # Returns a String MWS API host.
+      def host
+        HOSTS[locale]
+      end
+
+      # Sets the String marketplace ID.
+      #
+      # Raises a Missing Marketplace error if marketplace ID is missing.
+      def marketplace
+        @marketplace or raise MissingMarketplace
+      end
+
+      # Sets the String marketplace ID tag.
+      attr_writer :marketplace
+
+      # Returns a String MWS API URL path.
+      #
+      # Raises a Not Implemented Error if API is not implemented.
+      def path
+        case api
+        when :products
+          '/Products/2011-10-01'
+        else
+          raise NotImplementedError
+        end
+      end
+
+      # Sets the String seller ID.
+      #
+      # Raises a Missing Seller error if seller ID is missing.
+      def seller
+        @seller or raise MissingSeller
+      end
+
+      # Sets the String seller ID tag.
+      attr_writer :seller
+    end
+  end
+end

data/lib/vacuum/endpoint/product_advertising.rb

@@ -0,0 +1,34 @@
+module Vacuum
+  module Endpoint
+    # A Product Advertising API endpoint.
+    class ProductAdvertising < Base
+      # A list of Product Advertising API hosts.
+      HOSTS = {
+        'CA' => 'ecs.amazonaws.ca',
+        'CN' => 'webservices.amazon.cn',
+        'DE' => 'ecs.amazonaws.de',
+        'ES' => 'webservices.amazon.es',
+        'FR' => 'ecs.amazonaws.fr',
+        'IT' => 'webservices.amazon.it',
+        'JP' => 'ecs.amazonaws.jp',
+        'UK' => 'ecs.amazonaws.co.uk',
+        'US' => 'ecs.amazonaws.com'
+      }
+
+      # Returns a String Product Advertising API host.
+      def host
+        HOSTS[locale]
+      end
+
+      # Sets the String Associate tag.
+      #
+      # Raises a Missing Tag error if tag is missing.
+      def tag
+        @tag or raise MissingTag
+      end
+
+      # Sets the String Associate tag.
+      attr_writer :tag
+    end
+  end
+end

data/lib/vacuum/mws.rb

@@ -0,0 +1,8 @@
+%w(endpoint request response).each do |path|
+  require "vacuum/#{path}/mws"
+end
+
+module Vacuum
+  class MissingMarketplace < ArgumentError; end
+  class MissingSeller      < ArgumentError; end
+end

data/lib/vacuum/product_advertising.rb

@@ -0,0 +1,7 @@
+%w(endpoint request response).each do |path|
+  require "vacuum/#{path}/product_advertising"
+end
+
+module Vacuum
+  class MissingTag < ArgumentError; end
+end

data/lib/vacuum/request/base.rb

@@ -0,0 +1,96 @@
+module Vacuum
+  module Request
+    # An Amazon Web Services (AWS) API request.
+    class Base
+      # Returns the AWS API Endpoint.
+      attr :endpoint
+
+      # Creates a new request for given locale and credentials.
+      #
+      # Yields the AWS API endpoint if a block is given.
+      def initialize(&blk)
+        @parameters = {}
+        @endpoint = Endpoint.const_get(class_basename).new
+
+        configure &blk if block_given?
+      end
+
+      # Adds given parameters to the request.
+      #
+      # hsh - A Hash of parameter key and value pairs.
+      #
+      # Returns self.
+      def build(hsh)
+        hsh.each do |k, v|
+          k = Utils.camelize k.to_s if k.is_a? Symbol
+          @parameters[k] = v.is_a?(Array) ? v.join(',') : v.to_s
+        end
+
+        self
+      end
+
+      # Resets the request to the given parameters.
+      #
+      # hsh - A Hash of parameter key and value pairs.
+      #
+      # Returns self.
+      def build!(hsh = {})
+        @parameters = {}
+        build hsh
+      end
+
+      # Yields the AWS API Endpoint.
+      #
+      # Returns nothing.
+      def configure(&blk)
+        yield @endpoint
+      end
+
+      # Returns a Faraday::Connection.
+      #
+      # Yields a Faraday::Builder to configure the connection if a block is
+      # given.
+      def connection
+        @connection ||= Faraday.new do |builder|
+          builder.use Signature::Authentication, endpoint.secret
+
+          yield builder if block_given?
+
+          unless builder.handlers.any? { |h| h.name.include? ':Adapter:' }
+            builder.adapter Faraday.default_adapter
+          end
+        end
+      end
+
+      # Performs the AWS API request.
+      #
+      # Returns a Vacuum::Response::Base or a subclass thereof.
+      def get
+        res = connection.get url
+        Response.const_get(class_basename).new res.body, res.status
+      end
+
+      # Returns the Hash parameters of the AWS API request.
+      def parameters
+        default_parameters.merge @parameters
+      end
+
+      # Raises a Not Implemented Error.
+      #
+      # When implemented, this should return an Addressable::URI.
+      def url
+        raise NotImplementedError
+      end
+
+      private
+
+      def class_basename
+        self.class.name.split('::').last
+      end
+
+      def default_parameters
+        { 'AWSAccessKeyId' => endpoint.key }
+      end
+    end
+  end
+end

data/lib/vacuum/request/mws.rb

@@ -0,0 +1,24 @@
+module Vacuum
+  module Request
+    # A Marketplace Web Services (MWS) API request.
+    class MWS < Base
+      # Returns the Addressable::URI URL of the MWS API request.
+      def url
+        Addressable::URI.new :scheme        => 'https',
+                             :host          => endpoint.host,
+                             :path          => endpoint.path,
+                             :query_values  => parameters
+      end
+
+      private
+
+      def default_parameters
+        super.merge 'MarketplaceId'    => endpoint.marketplace,
+                    'SellerId'         => endpoint.seller,
+                    'Service'          => 'AWSECommerceService',
+                    'SignatureMethod'  => 'HmacSHA256',
+                    'SignatureVersion' => 2
+      end
+    end
+  end
+end

data/lib/vacuum/request/product_advertising.rb

@@ -0,0 +1,90 @@
+module Vacuum
+  module Request
+    # A Product Advertising API request.
+    class ProductAdvertising < Base
+      # Looks up attributes of up to twenty items.
+      #
+      # item_ids   - Splat Array of item IDs. The last element may optionally
+      #              specify a Hash of parameter key and value pairs.
+      #
+      # Examples
+      #
+      #   request.find '0679753354', response_group: 'Images'
+      #
+      # Returns a Vacuum::Response.
+      def find(*item_ids)
+        given_params = item_ids.last.is_a?(Hash) ? item_ids.pop : {}
+
+        params =
+          case item_ids.size
+          when 1..10
+            {
+              'Operation' => 'ItemLookup',
+              'ItemId'    => item_ids
+            }.merge given_params
+          when 11..20
+            default = {
+              'Operation'       => 'ItemLookup',
+              'ItemId.1.ItemId' => item_ids.shift(10),
+              'ItemId.2.ItemId' => item_ids
+            }
+            given_params.reduce(default) do |a, (k, v)|
+              a.merge "ItemLookup.Shared.#{Utils.camelize k.to_s}" => v
+            end
+          else
+            raise ArgumentError, "Can't look up #{item_ids.size} items"
+          end
+        build! params
+
+        get
+      end
+
+      # Searches for items that satisfy the given criteria, including one or
+      # more search indices.
+      #
+      # index           - Symbol search index
+      # query_or_params - String keyword query or Hash of parameter key and
+      #                   value pairs (default: nil).
+      #
+      # Examples
+      #
+      #   # Search the entire Amazon catalog for Deleuze.
+      #   request.search :all, 'Deleuze'
+      #
+      #   # Search books for non-fiction titles authored by Deleuze and sort
+      #   # results by relevance.
+      #   request.search :books, power: 'author:lacan and not fiction',
+      #                          sort:  'relevancerank'
+      #
+      def search(index, query_or_params = nil)
+        params = case query_or_params
+                 when String
+                   { 'Keywords' => query_or_params }
+                 else
+                   query_or_params
+                 end
+        build! params.merge! 'Operation'   => 'ItemSearch',
+                             'SearchIndex' => Utils.camelize(index.to_s)
+
+        get
+      end
+
+      # Returns the Addressable::URI URL of the Product Advertising API
+      # request.
+      def url
+        Addressable::URI.new :scheme        => 'http',
+                             :host          => endpoint.host,
+                             :path          => '/onca/xml',
+                             :query_values  => parameters
+      end
+
+      private
+
+      def default_parameters
+        super.merge 'AssociateTag' => endpoint.tag,
+                    'Service'      => 'AWSECommerceService',
+                    'Version'      => '2011-08-01'
+      end
+    end
+  end
+end

data/lib/vacuum/request/signature/authentication.rb

@@ -0,0 +1,32 @@
+module Vacuum
+  module Request
+    module Signature
+      # Internal: Middleware that signs REST requests to various Amazon API
+      # endpoints.
+      class Authentication < Faraday::Middleware
+        # Initializes the middleware.
+        #
+        # app - An Object that responds to `call` and returns a
+        # Faraday::Response.
+        # secret - The String Amazon AWS access secret key.
+        def initialize(app, secret)
+          @secret = secret
+          super app
+        end
+
+        # Signs the request.
+        #
+        # env - A Hash that contains info about the request.
+        #
+        # Returns an Object that responds to `call` and returns a
+        # Faraday::Response.
+        def call(env)
+          builder = Builder.new env, @secret
+          builder.timestamp.sort_query.sign
+
+          @app.call builder.env
+        end
+      end
+    end
+  end
+end

data/lib/vacuum/request/signature/builder.rb

@@ -0,0 +1,70 @@
+module Vacuum
+  module Request
+    module Signature
+      # Internal: Signs a request to an Amazon API with an HMAC-SHA256
+      # signature.
+      class Builder
+        # Returns a Hash that contains info about the request.
+        attr :env
+
+        # Returns the String Amazon AWS access secret key.
+        attr :secret
+
+        # Initializes a new Builder.
+        #
+        # env - A Hash that contains info about the request.
+        def initialize(env, secret)
+          env[:url] = Addressable::URI.parse env[:url]
+          @env, @secret = env, secret
+        end
+
+        # Returns the String name of the HTTP method used by the request.
+        def method
+          env[:method].to_s.upcase
+        end
+
+        # Signs the request.
+        #
+        # Returns self.
+        def sign
+          url.query = url.query.to_s + "&Signature=#{Utils.encode signature}"
+          self
+        end
+
+        # Returns a String signature.
+        def signature
+          sha256 = OpenSSL::Digest::SHA256.new
+          hash = OpenSSL::HMAC.digest sha256, secret, string_to_sign
+
+          Base64.encode64(hash).chomp
+        end
+
+        # Sorts the URL query values of the request.
+        #
+        # Returns self.
+        def sort_query
+          url.query_values = url.query_values
+          self
+        end
+
+        # Returns a String to sign based on pseudo-grammar specified by Amazon.
+        def string_to_sign
+          [method, url.host, url.path, url.query].join "\n"
+        end
+
+        # Timestamps the request.
+        #
+        # Returns self.
+        def timestamp
+          url.query = url.query.to_s + "&Timestamp=#{Utils.encode Time.now.utc.iso8601}"
+          self
+        end
+
+        # Returns the Addressable::URI URL of the request.
+        def url
+          env[:url]
+        end
+      end
+    end
+  end
+end

data/lib/vacuum/request/utils.rb

@@ -0,0 +1,24 @@
+module Vacuum
+  module Request
+    module Utils
+      # Camelizes a value.
+      #
+      # val - A String value.
+      #
+      # Returns an upper-camelcased String.
+      def self.camelize(val)
+        val.split('_').map(&:capitalize).join
+      end
+
+      # Percent encodes a URI component.
+      #
+      # component - The String URI component to encode.
+      #
+      # Returns the String encoded component.
+      def self.encode(component)
+        Addressable::URI.encode_component \
+          component, Addressable::URI::CharacterClasses::UNRESERVED
+      end
+    end
+  end
+end

data/lib/vacuum/response/base.rb

@@ -0,0 +1,57 @@
+module Vacuum
+  module Response
+    # An Amazon Web Services (AWS) API response.
+    class Base
+      # Gets/Sets the String response body.
+      attr_accessor :body
+
+      # Gets/Sets the Integer HTTP response code.
+      attr_accessor :code
+
+      # Initializes a new Response.
+      #
+      # body - The String response body.
+      # code - An HTTP response code that responds to to_i.
+      def initialize(body, code)
+        @body, @code = body, code.to_i
+      end
+
+      # Queries the response.
+      #
+      # query - String attribute to be queried.
+      #
+      # Yields matching nodes to a given block if one is given.
+      #
+      # Returns an Array of matching nodes or the return values of the yielded
+      # block if latter was given.
+      def find(query)
+        path = if xml.namespaces.empty?
+                 "//#{query}"
+               else
+                 "//xmlns:#{query}"
+               end
+
+        xml.xpath(path).map do |node|
+          hsh = Utils.xml_to_hash node
+          block_given? ? yield(hsh) : hsh
+        end
+      end
+      alias [] find
+
+      # Returns a Hash representation of the response.
+      def to_hash
+        Utils.xml_to_hash xml
+      end
+
+      # Returns whether the HTTP response is OK.
+      def valid?
+        code == 200
+      end
+
+      # Returns an XML document.
+      def xml
+        @xml ||= Nokogiri::XML.parse @body
+      end
+    end
+  end
+end

data/lib/vacuum/response/mws.rb

@@ -0,0 +1,7 @@
+module Vacuum
+  module Response
+    # A Marketplace Web Services (MWS) API response.
+    class MWS < Base
+    end
+  end
+end