currency_cloud 0.5 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c3d01c436b1a1da0688c30dce2f273fef5b15ee9
-  data.tar.gz: a4cc4a7719b2c9de95d0628c9b9c2a7f6a332fc5
+  metadata.gz: 9d6cc6e85c0ee4e1d64341df25e70cc470f27e2a
+  data.tar.gz: fb7dc0195ec0f39ff88d35739dee63e0c5b5a02a
 SHA512:
-  metadata.gz: c312578d3bb0aa6f831ab88567c987943a342d995419deb63d5ed36a32b0f251c867114fa5dc8870d71c4d996657382939f26b9e382040d77bc28ce3a925ed4a
-  data.tar.gz: 42cd53dcffc54a796656728a3cdab39083fc4149bcc225d6e2d42d99b9d2e6e655c5c25516f1a1aa9642dcb62b265fb168f4ee3a50697a7156e800a123cec720
+  metadata.gz: f00785918f0a998f708a2dfde29b667f804c019afbb25aae4c2d0af8e37bbd7cbe627f4ee328dd789da163d8670b7e09a37241cb21808dae2302d9f5a5a58d59
+  data.tar.gz: cc23502771aaa44dfa7ec5610af08279dde6de96cb7ed3df47a526624acbc1f344ad57c9a38cdf38568a535be09f2d3945a2dd3d7b346d6fb92cef01ef528747

data/.gitignore

@@ -1 +1,2 @@
 .DS_Store
+*.gem

data/README.md

@@ -1,10 +1,153 @@
-[![Build Status](https://travis-ci.org/CurrencyCloud/currencycloud-ruby.png?branch=master)](https://travis-ci.org/CurrencyCloud/currencycloud-ruby)
+[![Gem Version](https://badge.fury.io/rb/currency_cloud.svg)](http://badge.fury.io/rb/currency_cloud) [![Build Status](https://travis-ci.org/CurrencyCloud/currencycloud-ruby.png?branch=master)](https://travis-ci.org/CurrencyCloud/currencycloud-ruby)
 
-### TODO
+# Currency Cloud
 
-- Additional debug logging
-- Update from object (.save method)
-- Delete from object (.delete method)
-- Relationships: has_many, has_one, belongs_to
-- pagination - .next_page, .previous_page
-- On behalf of
+This is the official Ruby SDK for v2 of Currency Cloud's API. Additional documentation 
+for each API endpoint can be found at [connect.currencycloud.com][connect]
+
+## Installation
+
+You don't need this source code unless you want to modify the gem. If
+you just want to use the library in your application, you should run:
+
+  `gem install currency_cloud`
+
+If you want to build the gem from source:
+
+  `gem build currency_cloud.gemspec`
+
+## Supported Ruby versions
+
+This library aims to support and is [tested against][travis] the following Ruby
+implementations:
+
+* MRI 1.9.3
+* MRI 2.0.0
+* MRI 2.1.0
+* MRI 2.2.0
+* [JRuby][jruby]
+* [Rubinius][rubinius]
+
+# Usage
+
+```ruby
+require 'currency_cloud'
+
+## Configure ##
+CurrencyCloud.login_id = '<your login id>'
+CurrencyCloud.api_key = '<your api key>'
+CurrencyCloud.environment = :demonstration # use :production when ready
+
+## Make API calls ##
+currencies = CurrencyCloud::Reference.currencies
+#[#<CurrencyCloud::Currency:0x3fcb6d03960c {"code"=>"AED", "decimal_places"=>2, "name"=>"United Arab Emirates Dirham"}>,
+# #<CurrencyCloud::Currency:0x3fcb6d0390f8 {"code"=>"AUD", "decimal_places"=>2, "name"=>"Australian Dollar"}>,
+# #<CurrencyCloud::Currency:0x3fcb6d038d24 {"code"=>"CAD", "decimal_places"=>2, "name"=>"Canadian Dollar"}>,
+# <snip .../>
+# #<CurrencyCloud::Currency:0x3fcb6d0295b8 {"code"=>"TRY", "decimal_places"=>2, "name"=>"Turkish Lira"}>,
+# #<CurrencyCloud::Currency:0x3fcb6d028fc8 {"code"=>"USD", "decimal_places"=>2, "name"=>"United States Dollar"}>,
+# #<CurrencyCloud::Currency:0x3fcb6d0288d4 {"code"=>"ZAR", "decimal_places"=>2, "name"=>"South African Rand"}>]
+
+balances = CurrencyCloud::Balance.find
+
+#<CurrencyCloud::Balances:0x007f96da812838
+# @collection=
+#  [#<CurrencyCloud::Balance:0x3fcb6d4093b8 {"id"=>"5a998e06-3eb7-46d6-ba58-f749864159ce", "account_id"=>"e7483671-5dc6-0132-e126-002219414986", "currency"=>"GBP", "amount"=>"20034.78", "created_at"=>"2014-12-04T09:50:35+00:00", "updated_at"=>"2015-03-23T14:33:37+00:00"}>,
+#   #<CurrencyCloud::Balance:0x3fcb6d4089b8 {"id"=>"7b3796d0-35f3-4f47-8554-8020750a8f9d", "account_id"=>"e7483671-5dc6-0132-e126-002219414986", "currency"=>"EUR", "amount"=>"3012.16", "created_at"=>"2014-12-04T09:50:41+00:00", "updated_at"=>"2015-04-13T08:22:50+00:00"}>,
+# @pagination=
+#  #<CurrencyCloud::Pagination total_entries=5, total_pages=1, current_page=1, per_page=25, previous_page=-1, next_page=-1, order="created_at", order_asc_desc="asc">>
+```
+
+## On Behalf Of
+If you want to make calls on behalf of another user (e.g. someone who has a sub-account with you), you 
+can execute certain commands 'on behalf of' the user's contact_id. Here is an example:
+
+```ruby
+CurrencyCloud.on_behalf_of("c6ece846-6df1-461d-acaa-b42a6aa74045") do
+  beneficiary = CurrencyCloud::Beneficiary.create(<params>)
+  conversion = CurrencyCloud::Conversion.create(<params>)
+  payment = CurrencyCloud::Payment.create(<params>)
+end
+```
+
+Alternatively, you can just merge it with an existing params `Hash`, for example:
+
+```ruby
+CurrencyCloud::Account.create(account_name: 'My Test User', on_behalf_of: "c6ece846-6df1-461d-acaa-b42a6aa74045")
+```
+
+Each of the above transactions will be executed in scope of the limits for that contact and linked to that contact. Note
+that the real user who executed the transaction will also be stored.
+
+
+## Errors
+When an error occurs in the API, the library aims to give us much information
+as possible. Here is an example:
+
+```yaml
+CurrencyCloud::BadRequestError
+---
+platform: Ruby 1.9.3
+request:
+  parameters:
+    login_id: non-existent-login-id
+    api_key: ef0fd50fca1fb14c1fab3a8436b9ecb57528f0
+  verb: post
+  url: https://devapi.thecurrencycloud.com/v2/authenticate/api
+response:
+  status_code: 400
+  date: Wed, 29 Apr 2015 22:46:53 GMT
+  request_id: 2775253392756800903
+errors:
+- field: api_key
+  code: api_key_length_is_invalid
+  message: api_key should be 64 character(s) long
+  params:
+    length: 64
+```
+
+This is split into 5 sections:
+
+1. Error Type: In this case `BadRequestError` represents an HTTP 400 error
+2. Platform: The Ruby implementation that was used e.g. 'Ruby 2.2' or 'Ruby 1.9.3 (JRuby 1.7.8)''
+3. Request: Details about the HTTP request that was made e.g. the POST parameters
+4. Response: Details about the HTTP response that was returned e.g. HTTP status code
+5. Errors: A list of errors that provide additional information
+
+The final section contains valuable information:
+
+- Field: The parameter that the error is linked to
+- Code: A code representing this error
+- Message: A human readable message that explains the error
+- Params: A hash that contains dynamic parts of the error message for building custom error messages
+
+When troubleshooting API calls with Currency Cloud support, including the full
+error in any correspondence can be very helpful.
+
+# Development
+
+Test cases can be run with: `bundle exec rspec`. There is also a `Guardfile` that 
+is useful for continuously rerunning tests while you develop.
+
+## Dependencies
+* [HTTParty][httparty]
+* [json][json]
+
+## Versioning
+
+This project uses [semantic versioning][semver]. You can safely
+express a dependency on a major version and expect all minor and patch versions
+to be backwards compatible.
+
+# Copyright
+
+Copyright (c) 2015 Currency Cloud. See [LICENSE][license] for details.
+
+[connect]:   https://connect.currencycloud.com/documentation/getting-started/introduction
+[travis]:    https://travis-ci.org/CurrencyCloud/currencycloud-ruby
+[jruby]:     http://jruby.org/
+[rubinius]:  http://rubini.us/
+[httparty]:  https://github.com/jnunemaker/httparty
+[json]:      https://github.com/intridea/multi_json
+[semver]:    http://semver.org/
+[license]:   LICENSE.md

data/currency_cloud.gemspec

@@ -11,6 +11,7 @@ spec = Gem::Specification.new do |s|
   s.email = ['liam.mcandrew@currencycloud.com', 'richard.nienaber@currencycloud.com']
   s.homepage = 'https://connect.currencycloud.com/documentation/getting-started/introduction'
   s.licenses = ['MIT']
+  s.required_ruby_version = '>= 1.9'
 
   s.add_dependency('httparty', '~> 0.13')
   s.add_dependency('json', '~> 1.8')

data/lib/currency_cloud.rb

@@ -3,10 +3,13 @@ require 'httparty'
 require 'json'
 
 require 'currency_cloud/resource'
+require 'currency_cloud/errors/error_utils'
 lib_path = File.join(File.dirname(__FILE__), '**/*.*')
 Dir[lib_path].sort.each { |f| require f}
 
 module CurrencyCloud
+  UUID_REGEX = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i
+
   class << self
      attr_accessor :environment, :login_id, :api_key, :token
   end
@@ -22,5 +25,16 @@ module CurrencyCloud
   
   def self.reset_session
     @session = nil
+    @token = nil
+  end
+
+  def self.on_behalf_of(contact_id)
+    raise CurrencyCloud::GeneralError, '#on_behalf_of has already been set' unless session.on_behalf_of.nil?
+    raise CurrencyCloud::GeneralError, 'contact id for on behalf of is not a UUID' unless UUID_REGEX.match(contact_id)
+
+    session.on_behalf_of = contact_id
+    yield
+  ensure
+    session.on_behalf_of = nil
   end
 end

data/lib/currency_cloud/actions/delete.rb

@@ -4,12 +4,18 @@ module CurrencyCloud
     module Delete
 
       # TODO: Set state to be deleted
-      # TODO: Add .delete instance method
       # TODO: Disable all actionable methods / freeze?
       
       def delete(id)
         post("#{id}/delete")
       end       
     end
+
+    module InstanceDelete
+      def delete
+        self.class.delete(id)
+        self
+      end       
+    end
   end
 end

data/lib/currency_cloud/actions/save.rb

@@ -0,0 +1,14 @@
+module CurrencyCloud
+  module Actions
+    module Save
+      def save
+        return self if changed_attributes.empty?
+        
+        params = Hash[changed_attributes.map { |k| [k, self.send(k)] }]
+        post(id, params)
+        changed_attributes.clear
+        self
+      end
+    end
+  end
+end

data/lib/currency_cloud/errors/api_error.rb

@@ -1,5 +1,6 @@
 module CurrencyCloud
   class ApiErrorMessage
+
     attr_reader :field, :code, :message, :params
 
     def initialize(field, error)
@@ -8,13 +9,26 @@ module CurrencyCloud
       @message = error['message']
       @params = error['params']
     end
-  end
 
+    def to_h
+      {
+        'field' => field,
+        'code' => code,
+        'message' => message,
+        'params' => params
+      }
+    end
+  end
 
   class ApiError < StandardError
+    include ErrorUtils
+
     attr_reader :code, :messages, :raw_response, :status_code
 
-    def initialize(raw_response)
+    def initialize(verb, route, params, raw_response)
+      @verb = verb
+      @route = route
+      @params = params
       @raw_response = raw_response
       @status_code = raw_response.code
       errors = raw_response.parsed_response
@@ -27,6 +41,28 @@ module CurrencyCloud
         end
       end
     end
+
+    def to_s
+      class_name = super
+
+      string_params = Hash[@params.map { |k, v| [k.to_s, v.to_s]}]
+
+      error_details = {
+        'platform' => platform,
+        'request' => {
+          'parameters' => string_params,
+          'verb' => @verb.to_s,
+          'url' => @route
+        },
+        'response' => {
+          'status_code' => status_code,
+          'date' => raw_response.headers['Date'],
+          'request_id' => (raw_response.headers['x-request-id'] || 0).to_i
+        },
+        'errors' => messages.map(&:to_h)
+      }
+      "#{class_name}#{$/}#{YAML.dump(error_details)}"
+    end
   end
 
   class BadRequestError < ApiError; end

data/lib/currency_cloud/errors/error_utils.rb

@@ -0,0 +1,14 @@
+module CurrencyCloud
+  module ErrorUtils
+    def platform
+      base = "ruby-#{RUBY_VERSION}"
+      implementation = case RUBY_ENGINE
+                       when 'ruby' then ''
+                       when 'jruby' then ' (jruby-#{JRUBY_VERSION})"'
+                       when 'rbx' then ' (rbx-#{Rubinius::VERSION})'
+                       else ' (other)'
+                       end
+      "#{base}#{implementation}"
+    end
+  end
+end

data/lib/currency_cloud/errors/general_error.rb

@@ -0,0 +1,5 @@
+module CurrencyCloud
+
+  class GeneralError < StandardError; end
+
+end

data/lib/currency_cloud/errors/unexpected_error.rb

@@ -1,10 +1,32 @@
 module CurrencyCloud
   
   class UnexpectedError < StandardError
+    include ErrorUtils
+
     attr_reader :inner_error
 
-    def initialize(e)
+    def initialize(verb, route, params, e)
+      @verb = verb
+      @route = route
+      @params = params
       @inner_error = e
     end
+
+    def to_s
+      class_name = super
+
+      string_params = Hash[@params.map { |k, v| [k.to_s, v.to_s]}]
+
+      error_details = {
+        'platform' => platform,
+        'request' => {
+          'parameters' => string_params,
+          'verb' => @verb.to_s,
+          'url' => @route
+        },
+        'inner_error' => inner_error.to_s
+      }
+      "#{class_name}#{$/}#{YAML.dump(error_details)}"
+    end
   end   
 end

data/lib/currency_cloud/request_handler.rb

@@ -9,13 +9,15 @@ module CurrencyCloud
     end
     
     def get(route, params={}, opts={})
-      retry_authenticate('get', route, params, opts) do |url, options|
+      retry_authenticate('get', route, params, opts) do |url, params, options|
+        options.merge!(:query => params)
         HTTParty.get(url, options)
       end
     end
     
     def post(route, params={}, opts={})
-      retry_authenticate('post', route, params, opts) do |url, options|
+      retry_authenticate('post', route, params, opts) do |url, params, options|
+        options.merge!(:body => params)
         HTTParty.post(url, options)
       end
     end
@@ -23,46 +25,51 @@ module CurrencyCloud
     private
     def retry_authenticate(verb, route, params, opts)
       should_retry = opts[:should_retry].nil? ? true : opts.delete(:should_retry)
-      description = "to #{verb}: #{route}"
       
-      options = process_options(verb, params, opts)
+      params = process_params(params)
+      options = process_options(verb, opts)
+      full_url = build_url(route)
 
       response = nil
       retry_count = should_retry ? 0 : 2
       while retry_count < 3
-        response = yield(full_url(route), options)
+        response = yield(full_url, params, options)
         break unless response.code == 401 && should_retry
         session.reauthenticate
         retry_count += 1
       end
-      
-      process_response(response)
+
+      response_handler = CurrencyCloud::ResponseHandler.new(verb, full_url, params, response)
+      response_handler.process
+    rescue ApiError, UnexpectedError
+      raise
     rescue => e
-      raise if e.class.ancestors.include?(ApiError) || e.is_a?(UnexpectedError)
-      raise UnexpectedError.new(e)
+      raise UnexpectedError.new(verb, full_url, params, e)
     end
 
-    def process_options(verb, params, opts)
+    def process_options(verb, opts)
       options = {:headers => headers }
-      params_key = verb == :get ? :query : :body
-      options[params_key] = params
-      options.merge!(opts)
       # options[:debug_output] = $stdout
-      options
+      options.merge(opts)
+      # options
+    end
+
+    def process_params(params)
+      if session && session.on_behalf_of && CurrencyCloud::UUID_REGEX.match(session.on_behalf_of)
+        params.merge!(on_behalf_of: session.on_behalf_of)  
+      end
+      
+      params
     end
 
     def headers
       headers = {}
-      headers['X-Auth-Token'] = session.token if session.token
+      headers['X-Auth-Token'] = session.token if session && session.token
       headers
     end
         
-    def full_url(route)
+    def build_url(route)
       "#{session.environment_url}/#{CurrencyCloud::ApiVersion}/" + route
     end
-    
-    def process_response(response)
-      CurrencyCloud::ResponseHandler.process(response)
-    end
   end
 end