invisiblehand 0.1.0

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.rvmrc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+invisiblehand.yml
+spec/invisiblehand.yml

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in invisiblehand.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Sam Rose
+
+MIT License
+
+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.md

@@ -0,0 +1,124 @@
+# InvisibleHand API Client Ruby
+
+A Ruby client library to the InvisibleHand API. Allows for very easy
+programmatic access to the Invisible Hand API from Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'invisiblehand'
+
+And then execute:
+
+    $ bundle
+
+Alternately you can just install directly through the `gem` command:
+
+    $ gem install invisiblehand
+
+## Usage
+
+The first thing you must do in order to use this gem is create a configuration
+that contains your app ID and app key. You can obtain these from the Invisible
+Hand API website:
+[https://developer.getinvisiblehand.com/](https://developer.getinvisiblehand.com/).
+
+The sample configuration in this repository gives you a taste of what the config
+should look like. The gem will look for the config in the following locations in
+the following order:
+
+    - The path or Hash sent to the constructor
+    - An ENV variable called INVISIBLEHAND_CONFIG
+    - The current working directory at: ./invisiblehand.yml
+
+Some example usage:
+
+``` ruby
+require 'invisiblehand'
+
+# Instantiate the API object using the default config location
+# ./invisiblehand.yml
+api = InvisibleHand::API.new
+
+# Instantiate the API object with a hard coded, not-in-file config.
+api = InvisibleHand::API.new :app_id => "id", :app_key => "key"
+
+# Instantiate the API object from a path to a file.
+api = InvisibleHand::API.new "path/to/invisiblehand.yml"
+
+# Search for products that match the query "ipad"
+api.products({
+  :query => "ipad"
+})
+#=> A massive hash that you can find details of at:
+#     https://developer.getinvisiblehand.com/documentation
+
+# Search for products in a different region with a load of other relevant
+# options
+api.products({
+  :query => "galaxy",    # Search term
+  :region => "ca",       # Which region to query
+  :sort => "popularity", # What to order results by
+  :order => "desc",      # Direction to order results by
+  :size => "100"         # Number of results to return
+})
+#=> A massive hash that you can find details of at:
+#     https://developer.getinvisiblehand.com/documentation
+
+# Do a live price search on a product (price comes back as the currency in the
+# URL you specify. On amazon.com you get dollars, amazon.co.uk you get pounds.)
+api.live_price "http://www.amazon.com/gp/product/B005SUHRZS"
+#=> 11.25
+
+# You can also specify an Invisible Hand API link to the live_price method and
+# it will work fine.
+api.live_price "http://api.invisiblehand.co.uk/v1/pages/live_price?url=http%3A%2F%2Fwww.amazon.com%2Fgp%2Fproduct%2FB007PRHNHO"
+
+# Search for a specific product by its Invisible Hand ID
+api.product "f619c3e117d50d1a2b10930e5b202336"
+#=> A hash containing details of this item. More info at:
+#     https://developer.getinvisiblehand.com/documentation
+
+```
+
+### Errors
+
+If the API returns any error information, an `InvisibleHand::Error::APIError` is
+thrown and the `#message` method of the error object will contain the error
+output from the API.
+
+### Logging
+
+The InvisibleHand gem does have debug logging that goes to an internal `Logger`
+object. It should not output anything higher than the debug level, which it does
+when the `DEBUG` environment variable is set.
+
+If you wish to override the default logging object it builds internally, which
+outputs to STDOUT, you can do so with the following code:
+
+``` ruby
+require 'invisiblehand'
+
+# Ignore all InvisibleHand logging.
+InvisibleHand.logger = Logger.new('/dev/null')
+```
+
+## Debugging
+
+The gem looks for a DEBUG environment variable. If DEBUG is set, debugging
+information will be printed out to the screen. This includes URL information
+every time an API call is made.
+
+## Development
+
+To run tests, first you will need a valid `invisiblehand.yml` config file inside
+the `spec/` directory. The config you specify must be able to make API calls.
+
+Once you have confirmed this, you can run tests with the following command:
+
+    $ rake
+
+And if you wish to see debugging information:
+
+    $ DEBUG=true rake

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+task :default => [:test]
+
+desc "Run all tests"
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = '-cfs'
+end

data/invisiblehand.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/invisiblehand/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Sam Rose"]
+  gem.email         = ["developers@getinvisiblehand.com"]
+  gem.description   = %q{Ruby API client library to the InvisibleHand API.}
+  gem.summary       = %q{Allows for easy programmatic access to the InvisibleHand API.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "invisiblehand"
+  gem.require_paths = ["lib"]
+  gem.version       = InvisibleHand::VERSION
+
+  # Dependencies
+  gem.add_dependency('rest-client')
+  gem.add_dependency('json')
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('rspec')
+end

data/invisiblehand.sample.yml

@@ -0,0 +1,11 @@
+:app_id:  "your app id here"
+:app_key: "your app key here"
+
+# The endpoint is the region of the API you would like to hit. The regions are
+# detailed in the developer documentation:
+#
+#   https://developer.getinvisiblehand.com/documentation#intro
+#
+# The option will default to the US if you do not explicitly specify it.
+#
+# :endpoint: us.api.invisiblehand.co.uk

data/lib/invisiblehand.rb

@@ -0,0 +1,23 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH << libdir unless $LOAD_PATH.include? libdir
+
+require 'cgi'
+require 'yaml'
+require 'logger'
+require 'rest_client'
+require 'json'
+require 'benchmark'
+
+# Requires all .rb file in a given directory.
+def require_all path
+  Dir[File.join(File.dirname(__FILE__), path, '*.rb')].each { |f| require f }
+end
+
+# Logger is required early because it's a dependency of other classes.
+require 'invisiblehand/logger'
+
+require_all 'invisiblehand'
+
+module InvisibleHand
+  DEBUG = !!ENV['DEBUG']
+end

data/lib/invisiblehand/api.rb

@@ -0,0 +1,110 @@
+module InvisibleHand
+  class API
+    include InvisibleHand::Logger
+    attr_accessor :config
+
+    # When initializing a new instance of `InvisibleHand::API`, you can specify
+    # configuration in one of three ways:
+    #
+    #   require 'invisiblehand'
+    #
+    #   # This looks first for an environment variable called
+    #   # "INVISIBLEHAND_CONFIG", which should contain a file path to a config
+    #   # YAML file. Failing that, "./invisiblehand.yml" is used, looking for
+    #   # the config YAML file in the current directory.
+    #   api = InvisibleHand::API.new
+    #
+    #   # This one takes a string argument which should be a valid file path to
+    #   # the YAML config file.
+    #   api = InvisibleHand::API.new "path/to/invisiblehand.yml"
+    #
+    #   # Or you can do a literal hash config. This requires no YAML config
+    #   # file.
+    #   api = InvisibleHand::API.new :api_key => "...", :app_id => "..."
+    #
+    # Examples of the configuration variables you can pass in can be found in
+    # the "invisiblehand.sample.yml" file in this gem's GitHub repository.
+    def initialize conf = nil
+      if conf.is_a? Hash
+        @config = conf
+      elsif conf.is_a? String
+        @config = YAML.load_file(conf)
+      else
+        conf ||= ENV['INVISIBLEHAND_CONFIG'] || './invisiblehand.yml'
+        @config = YAML.load_file(conf)
+      end
+
+      # The @config[:development] flag exists to bypass the app_id and app_key
+      # check in this gem (not on the server) for internal testing reasons.
+      if valid_config?
+        raise Error::InvalidConfig.new
+          "Your config does not contain an app_id and app_key. " +
+            "Both are required to make API calls."
+      end
+
+      @config[:protocol] = @config[:use_ssl] == false ? "http://" : "https://"
+      @config[:endpoint] ||= "us.api.invisiblehand.co.uk"
+    end
+
+    def products opts = {}
+      api_call :get, "/v1/products", opts
+    end
+
+    def product id, opts = {}
+      api_call :get, "/v1/products/#{CGI.escape(id)}", opts
+    end
+
+    def live_price url, opts = {}
+      if url =~ /http:\/\/api\.invisiblehand/
+        url += url_params_from opts
+        json = api_raw_request :get, url
+        json["price"]
+      else
+        opts[:url] = url
+        json = api_call :get, "/v1/pages/live_price", opts
+        json["price"]
+      end
+    end
+
+    def api_call method, path, opts = {}
+      query = url_params_from opts
+      url   = "#{@config[:protocol]}#{@config[:endpoint]}#{path}?#{query}"
+
+      api_raw_request method, url
+    end
+
+    private
+
+    def api_raw_request method, url
+      logger.debug "API call URL: #{url}"
+
+      # Declare these early to avoid scoping programs in the timing block.
+      response = nil
+      json     = nil
+
+      elapsed = Benchmark.realtime do
+        response = RestClient.send(method, url) { |resp, req, res| resp }
+        json     = JSON.parse(response.body)
+      end
+
+      logger.debug "API call took #{elapsed.round(3)} seconds."
+      logger.debug "API json response: #{json.inspect}"
+
+      raise Error::APIError.new(json["error"]) if json["error"]
+
+      json
+    end
+
+    def url_params_from hash
+      hash.map do |key, value|
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      end.join("&")
+    end
+
+    def valid_config?
+      @config[:app_id].nil? and
+        @config[:app_key].nil? and
+        !@config[:development]
+    end
+  end
+end

data/lib/invisiblehand/errors.rb

@@ -0,0 +1,6 @@
+module InvisibleHand
+  module Error
+    class InvalidConfig < StandardError; end;
+    class APIError < StandardError; end;
+  end
+end

data/lib/invisiblehand/logger.rb

@@ -0,0 +1,32 @@
+module InvisibleHand
+  def self.logger
+    unless @logger
+      @logger = ::Logger.new(STDOUT)
+
+      if DEBUG
+        @logger.level = ::Logger::DEBUG
+      else
+        @logger.level = ::Logger::FATAL
+      end
+    end
+
+    @logger
+  end
+
+  # Override the InvisibleHand logger if you wish to have finer grained control
+  # over where your application's output is going.
+  #
+  #   InvisibleHand.logger = Logger.new('my/app/logs.log')
+  def self.logger= new_logger
+    @logger = new_logger
+  end
+
+  # Helper module for classes to include if they want to use the main
+  # InvisibleHand logger. Should be used for all in-gem logging as it is
+  # configurable by the end-user of the gem.
+  module Logger
+    def logger
+      InvisibleHand.logger
+    end
+  end
+end

data/lib/invisiblehand/version.rb

@@ -0,0 +1,5 @@
+module InvisibleHand
+  unless const_defined? :VERSION
+    VERSION = "0.1.0"
+  end
+end

data/spec/api_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+describe InvisibleHand::API do
+  # This file is not committed to this repository. You will have to create it
+  # yourself if you wish to run tests.
+  let(:api_config) { File.join(File.dirname(__FILE__), 'invisiblehand.yml') }
+
+  let(:api)        { InvisibleHand::API.new(api_config) }
+  let(:product)    { api.products["results"].first }
+  let(:product_id) { product["id"] }
+  let(:page)       { product["best_page"] }
+
+  describe "#products" do
+    subject    { api.products }
+    it         { should be_a Hash }
+    its(:keys) { should include "results" }
+    its(:keys) { should include "info" }
+  end
+
+  describe "#product" do
+    subject { product }
+    it      { should_not be_nil }
+  end
+
+  describe "#live_price" do
+    describe "with live price url" do
+      subject { api.live_price(page["live_price_url"]) }
+      it      { should be_a Float }
+    end
+
+    describe "with vanilla page url" do
+      subject { api.live_price(page["original_url"]) }
+      it      { should be_a Float }
+    end
+  end
+
+  describe "invalid config" do
+    specify "no app_id or api_key should throw error" do
+      expect do
+        InvisibleHand::API.new
+      end.to raise_error InvisibleHand::Error::InvalidConfig
+    end
+  end
+
+  describe "invalid api calls" do
+    describe "#product" do
+      specify "should throw InvisibleHand::Error::APIError on invalid ID" do
+        expect do
+          api.product "not a real id at all, lol"
+        end.to raise_error InvisibleHand::Error::APIError
+      end
+    end
+
+    describe "#live_price" do
+      specify "should throw InvisibleHand::Error::APIError on invalid URL" do
+        expect do
+          api.live_price "not a real url, rofl"
+        end.to raise_error InvisibleHand::Error::APIError
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'invisiblehand')

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: invisiblehand
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Sam Rose
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby API client library to the InvisibleHand API.
+email:
+- developers@getinvisiblehand.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- invisiblehand.gemspec
+- invisiblehand.sample.yml
+- lib/invisiblehand.rb
+- lib/invisiblehand/api.rb
+- lib/invisiblehand/errors.rb
+- lib/invisiblehand/logger.rb
+- lib/invisiblehand/version.rb
+- spec/api_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3768390383107493245
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3768390383107493245
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Allows for easy programmatic access to the InvisibleHand API.
+test_files:
+- spec/api_spec.rb
+- spec/spec_helper.rb