vacuum 0.1.3 → 0.2.0.pre

data/lib/vacuum/response/product_advertising.rb

@@ -0,0 +1,19 @@
+module Vacuum
+  module Response
+    # A Product Advertising API response.
+    class ProductAdvertising < Base
+      # Returns an Array of errors.
+      def errors
+        find 'Error'
+      end
+
+      # Returns whether the response has errors.
+      #
+      # Note that a response with errors is still technically valid, i.e. the
+      # response code is 200.
+      def has_errors?
+        errors.count > 0
+      end
+    end
+  end
+end

data/lib/vacuum/response/utils.rb

@@ -0,0 +1,48 @@
+module Vacuum
+  module Response
+    module Utils
+      # Builds a Hash from an XML document.
+      #
+      # xml - a Nokogiri::XML::Document or Nokogiri::XML::Element.
+      #
+      # Returns a Hash representation of the XML document.
+      def self.xml_to_hash(xml)
+        case xml
+        when Nokogiri::XML::Document
+          xml_to_hash xml.root
+        when Nokogiri::XML::Element
+          hsh = {}
+
+          xml.attributes.each_pair do |key, attribute|
+            hsh[key] = attribute.value
+          end
+
+          xml.children.each do |child|
+            result = xml_to_hash child
+
+            if child.name == 'text'
+              if hsh.empty?
+                return result
+              else
+                hsh['__content__'] = result
+              end
+            elsif hsh[child.name]
+              case hsh[child.name]
+              when Array
+                hsh[child.name] << result
+              else
+                hsh[child.name] = [hsh[child.name]] << result
+              end
+            else
+              hsh[child.name] = result
+            end
+          end
+
+          hsh
+        else
+          xml.content.to_s
+        end
+      end
+    end
+  end
+end

data/lib/vacuum/version.rb

@@ -1,3 +1,3 @@
 module Vacuum
-  VERSION = '0.1.3'
+  VERSION = '0.2.0.pre'
 end

data/lib/vacuum.rb

@@ -1,25 +1,45 @@
+# Standard library dependencies.
+require 'base64'
 require 'forwardable'
-require 'net/http'
 require 'openssl'
 require 'time'
 
-require 'knack'
-
-%w{request response}.each do |f|
-  require "vacuum/#{f}"
-end
+# External dependencies.
+require 'addressable/uri'
+require 'faraday'
+require 'nokogiri'
 
+# Internal dependencies.
+require 'vacuum/endpoint/base'
+require 'vacuum/request/base'
+require 'vacuum/request/signature/authentication'
+require 'vacuum/request/signature/builder'
+require 'vacuum/request/utils'
+require 'vacuum/response/base'
+require 'vacuum/response/utils'
+require 'vacuum/version'
 
-# Vacuum is a Ruby wrapper to the Amazon Product Advertising API.
+# Vacuum is a Ruby wrapper to various Amazon Web Services (AWS) APIs.
 module Vacuum
   class BadLocale     < ArgumentError; end
   class MissingKey    < ArgumentError; end
   class MissingSecret < ArgumentError; end
-  class MissingTag    < ArgumentError; end
 
   class << self
-    extend Forwardable
-
-    def_delegators Request, :new
+    def new(api, &blk)
+      case api
+      when /^mws/
+        require 'vacuum/mws'
+        Request::MWS.new do |config|
+          config.api = api.slice(4, api.size).to_sym 
+          blk.call config
+        end
+      when :product_advertising
+        require 'vacuum/product_advertising'
+        Request::ProductAdvertising.new &blk
+      else
+        raise NotImplementedError
+      end
+    end
   end
 end

data/spec/spec_helper.rb

@@ -1,14 +1,15 @@
-require 'rubygems'
-require 'bundler/setup'
 require 'rspec'
-
 begin
   require 'pry'
 rescue LoadError
 end
 
-require File.expand_path('../../lib/vacuum', __FILE__)
+require 'vacuum'
+require 'vacuum/mws'
+require 'vacuum/product_advertising'
 
 RSpec.configure do |c|
   c.treat_symbols_as_metadata_keys_with_true_values = true
 end
+
+Dir['./spec/support/**/*.rb'].each { |f| require f }

data/spec/support/shared_examples/endpoint.rb

@@ -0,0 +1,43 @@
+shared_examples 'an endpoint' do
+  describe '#key' do
+    it 'requires key to have been set' do
+      expect { endpoint.key }.to raise_error Vacuum::MissingKey
+    end
+  end
+
+  describe '#locale' do
+    it 'defaults to the US' do
+      endpoint.locale.should eql 'US'
+    end
+
+    context 'if not valid' do
+      before do
+        endpoint.locale = 'foo'
+      end
+
+      it 'raises an error' do
+        expect { endpoint.locale }.to raise_error Vacuum::BadLocale
+      end
+    end
+  end
+
+  describe '#secret' do
+    it 'requires secret to have been set' do
+      expect { endpoint.secret }.to raise_error Vacuum::MissingSecret
+    end
+  end
+
+  describe '#user_agent' do
+    it 'includes the library version number' do
+      endpoint.user_agent.should match /Vacuum\/[\d\w.]+\s/
+    end
+
+    it 'describes the Ruby interpreter' do
+      endpoint.user_agent.should match /Language=(?:j?ruby|rbx)/
+    end
+
+    it 'describes the host' do
+      endpoint.user_agent.should match /Host=[\w\d]+/
+    end
+  end
+end

data/spec/support/shared_examples/request.rb

@@ -0,0 +1,95 @@
+shared_examples 'a request' do
+  describe '#connection' do
+    let(:middleware) do
+      request.connection.builder.handlers
+    end
+
+    it 'returns a Faraday Connection' do
+      request.connection.should be_a Faraday::Connection
+    end
+
+    it 'adds Signature Authentication to middleware stack' do
+      middleware.should include Vacuum::Request::Signature::Authentication
+    end
+
+    it 'yields a builder' do
+      klass = Class.new Faraday::Middleware
+      request.connection do |builder|
+        builder.use klass
+      end
+      middleware.should include klass
+    end
+  end
+
+  describe '#endpoint' do
+    it 'returns an AWS API endpoint' do
+      request.endpoint.should be_a Vacuum::Endpoint::Base
+    end
+  end
+
+  describe '#build' do
+    it 'merges passed key and value pairs into the parameters' do
+      request.build 'Key' => 'value'
+      request.parameters['Key'].should eql 'value'
+    end
+
+    it 'casts Symbol keys to camel-cased String' do
+      request.build :foo_bar => 'value'
+      request.parameters.should have_key 'FooBar'
+    end
+
+    it 'does not modify String keys' do
+      request.build 'foo_bar' => 'value'
+      request.parameters.should have_key 'foo_bar'
+    end
+
+    it 'casts values to String' do
+      request.build 'Key' => 1
+      request.parameters['Key'].should eql '1'
+    end
+
+    it 'concatenates Array values with a comma' do
+      request.build 'Key' => ['foo', 'bar']
+      request.parameters['Key'].should eql 'foo,bar'
+    end
+
+    it 'returns self' do
+      request.build({}).should eql request
+    end
+  end
+
+  describe '#build!' do
+    it 'clears existing parameters' do
+      request.build 'Key' => 'value'
+      request.build!.parameters.should_not have_key 'Key'
+    end
+  end
+
+  describe '#configure' do
+    it 'configures the AWS API endpoint' do
+      request.configure do |config|
+        config.locale = 'JP'
+      end
+      request.endpoint.locale.should eql 'JP'
+    end
+  end
+
+  describe '#get' do
+    context 'given an implemented url' do
+      before do
+        request.stub!(:url).and_return Addressable::URI.parse 'http://example.com'
+      end
+
+      it 'returns a Response' do
+        request.get.should be_a Vacuum::Response::Base
+      end
+    end
+  end
+
+  describe '#parameters' do
+    it 'includes default parameters' do
+      request.parameters.should have_key 'AWSAccessKeyId'
+    end
+
+  end
+end

data/spec/support/shared_examples/response.rb

@@ -0,0 +1,51 @@
+shared_examples 'a response' do
+  let(:child_name) do
+    response.xml.children.first.name
+  end
+
+  describe '#find' do
+    it 'returns an Array of matches' do
+      response.find(child_name).should_not be_empty
+    end
+
+    it 'yields matches to a block' do
+      yielded = false
+      response.find(child_name) { yielded = true }
+      yielded.should be_true
+    end
+
+    it 'is aliased to []' do
+      response.find(child_name).should eql response[child_name]
+    end
+  end
+
+  describe '#to_hash' do
+    it 'casts response to a hash' do
+      response.to_hash.should be_a Hash
+    end
+  end
+
+  describe '#valid?' do
+    context 'when HTTP status is OK' do
+      it 'returns true' do
+        response.should be_valid
+      end
+    end
+
+    context 'when HTTP status is not OK' do
+      before do
+        response.code = 403
+      end
+
+      it 'returns false' do
+        response.should_not be_valid
+      end
+    end
+  end
+
+  describe '#xml' do
+    it 'returns a Nokogiri document' do
+      response.xml.should be_an_instance_of Nokogiri::XML::Document
+    end
+  end
+end

data/spec/vacuum/endpoint/base_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module Vacuum
+  module Endpoint
+    describe Base do
+      let(:endpoint) do
+        described_class.new
+      end
+
+      it_behaves_like 'an endpoint'
+
+      describe '#host' do
+        it 'is not implemented' do
+          expect { endpoint.host }.to raise_error NotImplementedError
+        end
+      end
+    end
+  end
+end

data/spec/vacuum/endpoint/mws_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+module Vacuum
+  module Endpoint
+    describe MWS do
+      let(:endpoint) do
+        described_class.new
+      end
+
+      describe '#host' do
+        it 'returns a host' do
+          endpoint.host.should match /amazon/
+        end
+      end
+
+      describe '#marketplace' do
+        it 'requires marketplace ID to have been set' do
+          expect { endpoint.marketplace }.to raise_error MissingMarketplace
+        end
+      end
+
+      describe '#seller' do
+        it 'requires seller ID to have been set' do
+          expect { endpoint.seller }.to raise_error MissingSeller
+        end
+      end
+
+      describe '#path' do
+        context 'when API type is set to Products' do
+          before do
+            endpoint.api = :products
+          end
+
+          it 'returns a URL path' do
+            endpoint.path.should match %r{/\w+/\w+}
+          end
+        end
+
+        context 'when API type is not implemented' do
+          it 'raises a Not Implemented Error' do
+            expect { endpoint.path }.to raise_error NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/spec/vacuum/endpoint/product_advertising_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+module Vacuum
+  module Endpoint
+    describe ProductAdvertising do
+      let(:endpoint) do
+        described_class.new
+      end
+
+      it_behaves_like 'an endpoint'
+
+      describe '#host' do
+        it 'returns a host' do
+          endpoint.host.should match /amazon/
+        end
+      end
+
+      describe '#tag' do
+        it 'requires tag to have been set' do
+          expect { endpoint.tag }.to raise_error MissingTag
+        end
+      end
+    end
+  end
+end

data/spec/vacuum/request/base_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+module Vacuum
+  module Request
+    describe Base do
+      let(:request) do
+        described_class.new do |config|
+          config.key = 'key'
+          config.secret = 'secret'
+        end
+      end
+
+      it_behaves_like 'a request'
+
+      describe '#url' do
+        it 'is not implemented' do
+          expect { request.url }.to raise_error NotImplementedError
+        end
+      end
+    end
+  end
+end

data/spec/vacuum/request/mws_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+module Vacuum
+  module Request
+    describe MWS do
+      let(:request) do
+        described_class.new do |config|
+          config.key = 'key'
+          config.marketplace = 'marketplace'
+          config.secret = 'secret'
+          config.seller = 'seller'
+        end
+      end
+
+      context 'when API type is set to Products' do
+        before do
+          request.configure do |config|
+            config.api = :products
+          end
+        end
+
+        it_behaves_like 'a request'
+      end
+    end
+  end
+end

data/spec/vacuum/request/product_advertising_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+
+module Vacuum
+  module Request
+    describe ProductAdvertising do
+      let(:request) do
+        described_class.new do |config|
+          config.key = 'key'
+          config.secret = 'secret'
+          config.tag = 'tag'
+        end
+      end
+
+      it_behaves_like 'a request'
+
+      describe '#find' do
+        before do
+          request.stub! :get
+        end
+
+        let(:parameters) do
+          request.parameters
+        end
+
+        context 'given no items' do
+          it 'raises an error' do
+            expect { request.find }.to raise_error ArgumentError
+          end
+        end
+
+        context 'given up to 10 items' do
+          before do
+            request.find *(1..10), :foo => 'bar'
+          end
+
+          it 'builds a single-batch query' do
+            parameters['ItemId'].split(',').should =~ (1..10).map(&:to_s)
+          end
+
+          it 'takes parameters' do
+            parameters['Foo'].should eql 'bar'
+          end
+        end
+
+        context 'given 11 to to 20 items' do
+          before do
+            request.find *(1..20), :foo => 'bar'
+          end
+
+          it 'builds a multi-batch query' do
+            first_batch = parameters['ItemId.1.ItemId'].split(',')
+            first_batch.should =~ (1..10).map(&:to_s)
+            second_batch = parameters['ItemId.2.ItemId'].split(',')
+            second_batch.should =~ (11..20).map(&:to_s)
+          end
+
+          it 'takes parameters' do
+            parameters['ItemLookup.Shared.Foo'].should eql 'bar'
+          end
+        end
+
+        context 'given over 20 items' do
+          it 'raises an error' do
+            expect { request.find *(1..21) }.to raise_error ArgumentError
+          end
+        end
+      end
+
+      describe '#search' do
+        let(:parameters) do
+          request.parameters
+        end
+
+        context 'when given a search index and a keyword' do
+          before do
+            request.search :foo, 'bar'
+          end
+
+          it 'builds a keyword search' do
+            parameters['Keywords'].should eql 'bar'
+          end
+
+          it 'sets the search index' do
+            parameters['SearchIndex'].should eql 'Foo'
+          end
+        end
+
+        context 'when given a search index and parameters' do
+          before do
+            request.search(:foo, :bar => 'baz')
+          end
+
+          it 'sets the parameters' do
+            parameters['Bar'].should eql 'baz'
+          end
+
+          it 'sets the search index' do
+            parameters['SearchIndex'].should eql 'Foo'
+          end
+        end
+      end
+    end
+  end
+end

data/spec/vacuum/request/signature/authentication_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+module Vacuum
+  module Request
+    module Signature
+      describe Authentication do
+        let(:middleware) do
+          described_class.new lambda { |env| env }, 'secret'
+        end
+
+        def result
+          env = { :url => 'http:://example.com/foo?Baz=2&Bar=1' }
+          middleware.call env
+        end
+
+        it 'sorts the query values' do
+          result[:url].query.should match /^Bar/
+        end
+
+        it 'timestamps the request' do
+          result[:url].query.should include 'Timestamp'
+        end
+
+        it 'signs the request' do
+          result[:url].query.should include 'Signature'
+        end
+      end
+    end
+  end
+end