cambio 0.1.0

data/.gitignore

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Phil Nash
+
+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,57 @@
+# Cambio
+
+A gem to wrap the Open Exchange Rates API from http://openexchangerates.org
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cambio'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cambio
+
+## Usage
+
+First you will need an App ID, you can sign up for one at https://openexchangerates.org/signup.
+
+    Cambio.configure do |config|
+      config.app_id
+    end
+
+Get the latest exchange rates
+
+    Cambio.latest
+
+You can also get the raw JSON response
+
+    Cambio.latest :raw => true
+
+Get the currencies available through the API
+
+    Cambio.currencies
+    # or
+    Cambio.currencies :raw => true
+
+Get the historical exchange rates
+
+    Cambio.historical('2012-08-17')
+    # or with a date object
+    Cambio.historical(Date.parse('17/08/2012'))
+
+
+
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['spec/*_spec.rb','spec/cambio/*_spec.rb']
+  t.verbose = true
+end
+task :spec => :test
+task :default => :test

data/cambio.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cambio/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Phil Nash"]
+  gem.email         = ["philnash@gmail.com"]
+  gem.description   = %q{A simple wrapper for the Open Exchange Rates API}
+  gem.summary       = %q{A simple wrapper for the Open Exchange Rates API}
+  gem.homepage      = "http://github.com/philnash/cambio"
+
+  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          = "cambio"
+  gem.require_paths = ["lib"]
+  gem.version       = Cambio::VERSION
+
+  gem.add_development_dependency 'vcr', '~> 2.2.4'
+  gem.add_development_dependency 'webmock', '~> 1.8.8'
+
+  gem.add_runtime_dependency 'faraday', '~> 0.8.1'
+  gem.add_runtime_dependency 'faraday_middleware', '~> 0.8.8'
+  gem.add_runtime_dependency 'hashie', '~> 1.2.0'
+end

data/lib/cambio.rb

@@ -0,0 +1,102 @@
+require "faraday"
+require "faraday_middleware"
+require "hashie"
+require 'faraday/raise_on_error'
+require "cambio/version"
+require "cambio/configuration"
+require "cambio/error"
+
+# Wrapper for the Open Exchange Rates API
+module Cambio
+  class << self
+    # Public: Configure the API wrapper. A convenience method that yields a
+    # configuration object on which you can set the app_id and endpoint.
+    #
+    # Examples
+    #
+    #   Cambio.configure do |config|
+    #     config.app_id = 'YOUR_APP_ID'
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Public: Access to the underlying configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Public: Retrieve the latest rates from the API
+    #
+    # opts - A hash of options to affect the returned result (default: {}):
+    #        :raw - A Boolean to describe whether you want the raw JSON response
+    #
+    # Examples
+    #
+    #   Cambio.latest
+    #   # => #<Hashie::Mash base="USD" ... >
+    #
+    #   Cambio.latest :raw => true
+    #   # => "{\n\t\"disclaimer\": \"This data..." ... }"
+    #
+    # # Returns a Hashie::Mash of the rates (or raw JSON, if raw is passed)
+    def latest(opts={})
+      response = connection(opts).get 'latest.json'
+      response.body
+    end
+
+    # Public: Retrieve the currencies supplied by the API
+    #
+    # opts - A hash of options to affect the returned result (default: {}):
+    #        :raw - A Boolean to describe whether you want the raw JSON response
+    #
+    # Examples
+    #
+    #   Cambio.currencies
+    #   # => #<Hashie::Mash AED="United Arab Emirates Dirham" ... >
+    #
+    #   Cambio.currencies
+    #   # => "{\n\t\"AED\": \"United Arab Emirates Dirham\", ... }"
+    #
+    # Returns a Hashie::Mash of the currencies (or raw JSON, if raw is passed)
+    def currencies(opts={})
+      response = connection(opts).get 'currencies.json'
+      response.body
+    end
+
+    # Public: Retrieve the historical rates supplied by the API
+    #
+    # date - A string in the format YYYY-MM-DD or a date object referring to the
+    #        day on which you want to get the rates from
+    # opts - A hash of options to affect the returned result (default: {}):
+    #        :raw - A Boolean to describe whether you want the raw JSON response
+    #
+    # Examples
+    #
+    #   Cambio.historical('2012-08-17')
+    #
+    #   Cambio.historical(Date.today)
+    #
+    # Returns a Hashie::Mash of the rates from the date specified (or raw JSON,
+    # if raw is passsed)
+    def historical(date, opts={})
+      date = date.strftime("%Y-%m-%d") if date.respond_to?(:strftime)
+      response = connection(opts).get "historical/#{date}.json"
+      response.body
+    end
+
+    private
+
+    # Internal: access to a faraday connection
+    def connection(opts={})
+      Faraday.new(:url => configuration.endpoint, :params => { :app_id => configuration.app_id }) do |conn|
+        unless opts[:raw]
+          conn.response :mashify
+          conn.response :json
+        end
+        conn.response :raise_on_error
+        conn.adapter Faraday.default_adapter  # make requests with Net::HTTP
+      end
+    end
+  end
+end

data/lib/cambio/configuration.rb

@@ -0,0 +1,31 @@
+module Cambio
+  # Internal: An object to hold the internal configuration of the Cambio module
+  class Configuration
+    # Public: Gets/Sets the String app_id
+    attr_accessor :app_id
+    # Public: Gets/Sets the String endpoint
+    attr_accessor :endpoint
+
+    # Internal: By default, don't set an app ID
+    DEFAULT_APP_ID = nil
+
+    # Internal: The default API endpoint, it can also be set to use https
+    DEFAULT_ENDPOINT = 'http://openexchangerates.org/api/'
+
+    # Internal: The configuration object should be initialized by the Cambio
+    # module
+    def initialize
+      @endpoint = DEFAULT_ENDPOINT
+    end
+
+    # Public: resets the internal configuration to the defaults
+    #
+    # Examples
+    #
+    #   configuration.reset
+    def reset
+      @endpoint = DEFAULT_ENDPOINT
+      @app_id   = DEFAULT_APP_ID
+    end
+  end
+end

data/lib/cambio/error.rb

@@ -0,0 +1,13 @@
+module Cambio
+  # Internal: Custom error class for all other Cambio errors
+  class Error < StandardError; end
+
+  # Internal: Raised when trying to use the API with the wrong or no credentials
+  class UnauthorisedError < Error; end
+
+  # Internal: Raised when 404 error is returned from the API
+  class NotFoundError < Error; end
+
+  # Internal: Raised when a 500 error is returned from the API
+  class ServerError < Error; end
+end

data/lib/cambio/version.rb

@@ -0,0 +1,3 @@
+module Cambio
+  VERSION = "0.1.0"
+end

data/lib/faraday/raise_on_error.rb

@@ -0,0 +1,32 @@
+require 'json' unless defined?(::JSON)
+module FaradayMiddleware
+  class RaiseOnError < Faraday::Response::Middleware
+    def on_complete(env)
+      case env[:status]
+      when 404
+        raise Cambio::NotFoundError, build_message(env)
+      when 401
+        raise Cambio::UnauthorisedError, build_message(env)
+      when 500
+        raise Cambio::ServerError, build_message(env)
+      when 400...600
+        raise Cambio::Error, build_message(env)
+      end
+    end
+
+    private
+
+    def build_message(env)
+      body = get_body(env[:body])
+      "#{env[:status]}: #{body['message']}. #{body['description']}"
+    end
+
+    def get_body(body)
+      if !body.nil? && !body.empty? && body.kind_of?(String)
+        parsed_body = ::JSON.parse(body)
+      end
+      parsed_body.nil? || parsed_body.empty? ? {} : parsed_body
+    end
+  end
+end
+Faraday.register_middleware :response, :raise_on_error => FaradayMiddleware::RaiseOnError

data/spec/cambio/configuration_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe Cambio::Configuration do
+  before do
+    @configuration = Cambio::Configuration.new
+  end
+
+  it 'should default to the http url' do
+    @configuration.endpoint.must_equal 'http://openexchangerates.org/api/'
+  end
+
+  it 'should default to no app id' do
+    @configuration.app_id.must_be_nil
+  end
+
+  describe 'setting the endpoint' do
+    before do
+      @configuration.endpoint = 'https://openexchangerates.org/api/'
+    end
+
+    it 'should update the endpoint' do
+      @configuration.endpoint.must_equal 'https://openexchangerates.org/api/'
+    end
+  end
+
+  describe 'setting the app_id' do
+    before do
+      @configuration.app_id = 'abc123'
+    end
+
+    it 'should set the app_id' do
+      @configuration.app_id.must_equal 'abc123'
+    end
+  end
+
+  describe 'resetting the configuration' do
+    before do
+      @configuration.app_id = 'abc123'
+      @configuration.endpoint = 'https://openexchangerates.org/api/'
+      @configuration.reset
+    end
+
+    it 'should reset the app_id to default' do
+      @configuration.app_id.must_be_nil
+    end
+
+    it 'should reset the endpoint to default' do
+      @configuration.endpoint.must_equal 'http://openexchangerates.org/api/'
+    end
+  end
+end

data/spec/cambio_spec.rb

@@ -0,0 +1,195 @@
+require File.expand_path('../spec_helper', __FILE__)
+
+describe Cambio do
+  describe 'when configuring with an api key' do
+    before do
+      Cambio.configure do |config|
+        config.app_id = 'bcc1d1ad9f4d4dd69b12a64c913857fe'
+      end
+    end
+
+    after do
+      Cambio.configuration.reset
+    end
+
+    it 'should be configured with an api key' do
+      Cambio.configuration.app_id.must_equal 'bcc1d1ad9f4d4dd69b12a64c913857fe'
+    end
+
+    it 'should be configured with an endpoint' do
+      Cambio.configuration.endpoint.must_equal 'http://openexchangerates.org/api/'
+    end
+
+    it 'should have a configuration object' do
+      Cambio.configuration.must_be_instance_of Cambio::Configuration
+    end
+
+    describe 'accessing the api' do
+      describe 'when getting the latest rates' do
+        before do
+          VCR.use_cassette 'latest' do
+            @latest = Cambio.latest
+          end
+        end
+
+        it 'should return a hashie' do
+          @latest.must_be_instance_of Hashie::Mash
+        end
+
+        [:disclaimer, :license, :timestamp, :base, :rates].each do |field|
+          it "should have the #{field}" do
+            @latest.must_respond_to(field)
+          end
+        end
+      end
+
+      describe 'when getting historical rates' do
+        describe 'with an object that responds to strftime' do
+          before do
+            @date = Time.at(1344896438)
+            VCR.use_cassette 'historical_date' do
+              @historical = Cambio.historical(@date)
+            end
+          end
+
+          it 'should return a hashie' do
+            @historical.must_be_instance_of Hashie::Mash
+          end
+
+          [:disclaimer, :license, :timestamp, :base, :rates].each do |field|
+            it "should have the #{field}" do
+              @historical.must_respond_to(field)
+            end
+          end
+
+          it 'must rause a not found error when the year doesn\'t exist' do
+            lambda {
+              VCR.use_cassette 'historical_missing' do
+                Cambio.historical('00000')
+              end
+            }.must_raise Cambio::NotFoundError
+          end
+        end
+
+        describe 'with a date string' do
+          before do
+            VCR.use_cassette 'historical_string' do
+              @historical = Cambio.historical('2011-02-01')
+            end
+          end
+
+          it 'should return a hashie' do
+            @historical.must_be_instance_of Hashie::Mash
+          end
+
+          [:disclaimer, :license, :timestamp, :base, :rates].each do |field|
+            it "should have the #{field}" do
+              @historical.must_respond_to(field)
+            end
+          end
+        end
+      end
+
+      describe 'when getting the currencies' do
+        before do
+          VCR.use_cassette 'currencies', do
+            @currencies = Cambio.currencies
+          end
+        end
+
+        it 'should return a hashie' do
+          @currencies.must_be_instance_of Hashie::Mash
+        end
+
+        it 'should  return a USD' do
+          @currencies['USD'].must_equal "United States Dollar"
+        end
+      end
+
+      describe 'when getting raw results' do
+        describe 'for the latest rates' do
+          before do
+            VCR.use_cassette 'latest' do
+              @latest = Cambio.latest(:raw => true)
+            end
+          end
+
+          it 'should return a JSON string' do
+            @latest.must_be_instance_of String
+          end
+        end
+
+        describe 'for historical rates' do
+          describe 'with a date object' do
+            before do
+              @date = Time.at(1344896438)
+              VCR.use_cassette 'historical_date' do
+                @historical = Cambio.historical(@date, :raw => true)
+              end
+            end
+
+            it 'should return a string' do
+              @historical.must_be_instance_of String
+            end
+          end
+
+          describe 'with a date string' do
+            before do
+              VCR.use_cassette 'historical_string' do
+                @historical = Cambio.historical('2011-02-01', :raw => true)
+              end
+            end
+
+            it 'should return a string' do
+              @historical.must_be_instance_of String
+            end
+          end
+        end
+
+        describe 'for the currencies' do
+          before do
+            VCR.use_cassette 'currencies' do
+              @currencies = Cambio.currencies(:raw => true)
+            end
+          end
+
+          it 'should return a JSON string' do
+            @currencies.must_be_instance_of String
+          end
+        end
+      end
+    end
+  end
+
+  describe 'when using with an incorrect api key' do
+    before do
+      Cambio.configure { |c| c.app_id = 'wrong' }
+    end
+
+    it 'must raise an error for latest' do
+      lambda {
+        VCR.use_cassette 'latest_unauth' do
+          Cambio.latest
+        end
+      }.must_raise Cambio::UnauthorisedError
+    end
+    it 'must raise an error for currencies' do
+      lambda {
+        VCR.use_cassette 'currencies_unauth' do
+          Cambio.currencies
+        end
+      }.must_raise Cambio::UnauthorisedError
+    end
+    it 'must raise an error for currencies' do
+      lambda {
+        VCR.use_cassette 'historical_unauth' do
+          Cambio.historical('2011-02-01')
+        end
+      }.must_raise Cambio::UnauthorisedError
+    end
+
+    after do
+      Cambio.configuration.reset
+    end
+  end
+end