omni_exchange 0.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d30d7e4e3e64ec5ad04a09977b9320fc3fa057b6467522f69e13f8b7449086d
-  data.tar.gz: ebfc182f603c08030550a23be4348f6126cfaa83cced86bd4af73fe7d2f485df
+  metadata.gz: 23f8e6cc867244781c587d8ba217e373dabd00c5bf78710b673d8e6f4b330cb0
+  data.tar.gz: fffb0e30a3bb6f953ff6a38afcf821023f0e9f898c91448c29e2a6697153bf5d
 SHA512:
-  metadata.gz: 94df50122f3b0f827111c2b8ea5af33fafc4ef3c3202a80b1d8de0170113283f2bcbb2f8216de175bb2e3bb584231e68b5be3687be4185fb3faac73748dd7658
-  data.tar.gz: e2aaa25ab94143cf25fb3b86ee659df937f75f197e0d48c06d0bb561dd732d7d6eff79ada826dad10accb17589900a1cb74190a7167fb3a931f8ccc39f041e6a
+  metadata.gz: a4fe1ff6099ab9d3662f3a4881303e6c3c7d380cfc49c559c09ca39f1a5a918e381fb017c45cb9552e4b7dd35f8c7f52beaa2762898eb84e43e737aa59f7999e
+  data.tar.gz: 67d7ae42c4ff478a18669cbbed4ac9c99ac81947402e671e8fec1f072d7e3eeacaf46f18b4570e23b675a7dd34c1ff44b34c051c947aa6a2766e50fc3531755e

data/.gitignore

@@ -14,3 +14,6 @@
 .env
 
 sandbox.rb
+omni_exchange-0.1.0.gem
+omni_exchange-0.2.0.gem
+omni_exchange-1.1.0.gem

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2022-06-20 08:25:31 UTC using RuboCop version 0.93.1.
+# on 2022-06-30 01:49:03 UTC using RuboCop version 0.93.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -9,13 +9,13 @@
 # Offense count: 2
 # Configuration parameters: IgnoredMethods.
 Metrics/AbcSize:
-  Max: 27
+  Max: 28
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods.
 # ExcludedMethods: refine
 Metrics/BlockLength:
-  Max: 26
+  Max: 27
 
 # Offense count: 1
 Naming/AccessorMethodName:
@@ -32,14 +32,22 @@ Style/Documentation:
     - 'lib/omni_exchange/providers/open_exchange_rates.rb'
     - 'lib/omni_exchange/providers/xe.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: scientific, engineering, integral
 Style/ExponentialNotation:
   Exclude:
     - 'spec/omni_exchange_spec.rb'
 
-# Offense count: 13
+# Offense count: 3
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'lib/sandbox.rb'
+
+# Offense count: 16
 # Cop supports --auto-correct.
 # Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https

data/Gemfile.lock

@@ -1,21 +1,26 @@
 PATH
   remote: .
   specs:
-    omni_exchange (0.1.0)
-      faraday
+    omni_exchange (1.1.1)
+      faraday (= 0.17.4)
+      money (~> 6.13.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
     coderay (1.1.3)
+    concurrent-ruby (1.1.10)
     diff-lcs (1.5.0)
     dotenv (2.7.6)
-    faraday (2.3.0)
-      faraday-net_http (~> 2.0)
-      ruby2_keywords (>= 0.0.4)
-    faraday-net_http (2.0.3)
+    faraday (0.17.4)
+      multipart-post (>= 1.2, < 3)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
     method_source (1.0.0)
+    money (6.13.8)
+      i18n (>= 0.6.4, <= 2)
+    multipart-post (2.2.3)
     parallel (1.22.1)
     parser (3.1.2.0)
       ast (~> 2.4.1)
@@ -51,7 +56,6 @@ GEM
     rubocop-ast (1.18.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.5)
     unicode-display_width (1.8.0)
     vcr (6.1.0)
 

data/README.md

@@ -1,6 +1,8 @@
 # OmniExchange
 
-OmniExchange converts currencies using up-to-the-minute foreign exchange rates data.
+OmniExchange converts currencies using up-to-the-minute foreign exchange rates.
+
+OmniExchange also supports fail-over logic and handles timeouts. In other words, if currency conversion isn't possible because an API data source cannot provide an exchange rate, OR if that data source times out, OmniExchange will retrieve exchange rate data seamlessly from another API data source.
 
 ## Installation
 
@@ -44,24 +46,34 @@ OmniExchange.configure do |config|
 end
 ```
 
-#### **Step 3) Convert Currency**
+#### **Step 3) Convert Currency and/or Get An Exchange Rate**
 
-To convert currency, all you have to do is call `OmniExchange.exchange_currency()`. This method requires you to pass the following four named parameters:
-1. amount: (Integer)the amount of the currency you want to convert. NOTE: OmniExchange will read this amount as being the smallest unit of a currency. In other words, if you pass `10` as the amount for USD, OmniExchange will read this as 10 cents, not 10 dollars.
+To convert currency and/or get an exchange rate, all you have to do is call `OmniExchange.get_fx_data()`. This method requires you to pass the following four named parameters:
+1. amount: (Integer) the amount of the currency you want to convert. NOTE: OmniExchange will read this amount as being the smallest unit of a currency. In other words, if you pass `10` as the amount for USD, OmniExchange will read this as 10 cents, not 10 dollars.
 2. base_currency: (String) the ISO Currency Code of the currency that you're exchanging from. ie. 'USD', 'JPY'
 3. target_currency: (String) the ISO Currency Code of the currency that you're exchanging to. ie. 'EUR', 'KRW'
-4. providers: (Array) the keys of the API providers that you want data from in order of preference. ie. [:xe, :open_exchange_rates]
+4. providers: (Array of Symbols) the keys of the API providers that you want data from in order of preference. ie. [:xe, :open_exchange_rates]
+
+What you get back is a hash containing:
+1. converted_amount: (BigDecimal) the amount of money exchanged from the base currency to the target currency
+2. exchange_rate: (BigDecimal) the rate used to calculate the converted_amount
+3. provider_class: (Class) the name of the provider class that supplied the exchange_rate (ie. OmniExchange::OpenExhangeRates)
 
-[For the sake of precise calculation](https://www.bigbinary.com/blog/handling-money-in-ruby), you'll get back a BigDecimal. Simply call `.to_f` to the result if you'd like to see a number that is easier to read.
+[For the sake of precise calculation](https://www.bigbinary.com/blog/handling-money-in-ruby), converted_amount and exchange_rate are BigDecimal. Simply call `.to_f` to the results if you'd like to see a number that is easier to read.
 
 
-Here is an example. Lets say I want to convert $10.00 US Dollars to Japanese Yen, and I want it converted using exchange rate data from Open Exchange Rates. If Open Exchange Rates fails, I'd like OmniExchange to try to use exchange rate data from Xe as a fallback.
+Here is an example. Lets say I want to convert $1.00 US Dollar to Japanese Yen, and I want it converted using exchange rate data from Open Exchange Rates. If Open Exchange Rates fails, I'd like OmniExchange to try to use exchange rate data from Xe as a fallback.
 
 ```ruby
-USD_to_JPY = OmniExchange.exchange_currency(amount: 1000, base_currency: "USD", target_currency: "JPY", providers: [:open_exchange_rates, :xe])
+USD_to_JPY = OmniExchange.get_fx_data(amount: 100, base_currency: 'USD', target_currency: 'JPY', providers: [:open_exchange_rates, :xe])
+
+puts USD_to_JPY # => { :converted_amount=>0.13566633333e3, :exchange_rate=>0.13566633333e1, :provider_class=>OmniExchange::OpenExchangeRates }
+
+puts USD_to_JPY[:converted_amount] # => 0.13566633333e3
+puts USD_to_JPY[:converted_amount].to_f # => 135.66633333
 
-puts USD_to_JPY # => 0.1345807e4 
-puts USD_to_JPY.to_f # => 1345.807
+puts USD_to_JPY[:exchange_rate] # => 0.13566633333e1
+puts USD_to_JPY[:exchange_rate].to_f # => 1.3566633333
 
 ```
 
@@ -73,7 +85,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/omni_exchange. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/omni_exchange/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and issues are welcome on GitHub at https://github.com/degica/omni_exchange. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/degica/omni_exchange/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -81,4 +93,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the OmniExchange project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/omni_exchange/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the OmniExchange project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/degica/omni_exchange/blob/master/CODE_OF_CONDUCT.md).

data/bin/console

@@ -5,8 +5,10 @@ require 'bundler/setup'
 require 'omni_exchange'
 require 'dotenv/load'
 require 'faraday'
+require 'money'
 require_relative '../lib/omni_exchange/provider'
 require_relative '../lib/omni_exchange/configuration'
+require_relative '../lib/omni_exchange/error'
 require_relative '../lib/omni_exchange/providers/xe'
 require_relative '../lib/omni_exchange/providers/open_exchange_rates'
 

data/lib/omni_exchange/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OmniExchange
+  # A custom error for an unknown or invalid currency
+  class UnknownCurrency < StandardError
+  end
+
+  # A custom error for failure to get data from a provider
+  class HttpError < StandardError
+  end
+end

data/lib/omni_exchange/provider.rb

@@ -4,7 +4,6 @@ module OmniExchange
   class Provider
     # @providers is a hash of registered providers that OmniExchange can request exchange rates data from
     @providers = {}
-    @currency_data = nil
 
     # This method registers providers by adding a provider's name as a key and a provider class as a value to
     #   @providers. This happens automatically on load at the top of the lib/omni_exchange.rb file when each
@@ -43,18 +42,13 @@ module OmniExchange
 
     # Some currencies, such as the US dollar, have subunits (ie. cents). Therefore, to make sure that currencies are
     #   exchanged accurately, a currency's subunit needs to be taken into account, and that's what this method does.
-    #   Subunit data of currencies is stored as @currency_data after being read from the currency_data.json file.
+    #   Subunit data is easily found through use of the RubyMoney gem.
     #
     # @param base_currency [String] the ISO Currency Code of the currency that you're exchanging from. A check is done
     #   on this currency to see if it has subunits (such as the US dollar having cents). ie. "USD", "JPY"
-    # @return [Float] the amount an exchange rate should be multiplied by to account for subunits
+    # @return [Float] the amount an exchange rate should be multiplied by to account for a currency's potential subunits
     def self.get_currency_unit(base_currency)
-      return 1.0 / @currency_data[base_currency.downcase]['subunit_to_unit'] if @currency_data
-
-      file = File.read(File.join(File.dirname(__FILE__), './currency_data.json'))
-      @currency_data = JSON.parse(file)
-
-      1.0 / @currency_data[base_currency.downcase]['subunit_to_unit']
+      1.0 / Money::Currency.wrap(base_currency).subunit_to_unit
     end
   end
 end

data/lib/omni_exchange/providers/open_exchange_rates.rb

@@ -19,9 +19,7 @@ module OmniExchange
       config = OmniExchange.configuration.provider_config[:open_exchange_rates]
       app_id = config[:app_id]
 
-      api = Faraday.new(ENDPOINT_URL) do |conn|
-        conn.response :json, parser_options: { symbolize_names: true }
-      end
+      api = Faraday.new(OmniExchange::OpenExchangeRates::ENDPOINT_URL)
 
       begin
         response = api.get do |req|
@@ -32,11 +30,12 @@ module OmniExchange
       rescue Faraday::Error, Faraday::ConnectionFailed => e
         raise e.class, 'Open Exchange Rates has timed out.'
       end
-      exchange_rate = response.body[:rates][target_currency.to_sym].to_d
 
-      currency_unit = get_currency_unit(base_currency)
+      exchange_rate = JSON.parse(response.body, symbolize_names: true)[:rates][target_currency.to_sym].to_d
+
+      currency_unit = get_currency_unit(base_currency).to_d
 
-      exchange_rate * currency_unit
+      (exchange_rate * currency_unit).to_d
     end
 
     # when this file is required at the top of lib/omni_exchange.rb, this method call is run and allows

data/lib/omni_exchange/providers/xe.rb

@@ -21,9 +21,9 @@ module OmniExchange
       api_key = config[:api_key]
       currency_unit = get_currency_unit(base_currency)
 
-      api = Faraday.new(ENDPOINT_URL) do |conn|
-        conn.request :authorization, :basic, api_id, api_key
-        conn.response :json, parser_options: { symbolize_names: true }
+      api = Faraday.new(OmniExchange::Xe::ENDPOINT_URL) do |f|
+        f.request :basic_auth, api_id, api_key
+        f.adapter :net_http
       end
 
       begin
@@ -36,7 +36,7 @@ module OmniExchange
         raise e.class, 'xe.com has timed out.'
       end
 
-      response.body[:to][0][:mid].to_d
+      JSON.parse(response.body, symbolize_names: true)[:to][0][:mid].to_d
     end
 
     # when this file is required at the top of lib/omni_exchange.rb, this method call is run and allows

data/lib/omni_exchange/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniExchange
-  VERSION = '0.1.0'
+  VERSION = '1.1.1'
 end

data/lib/omni_exchange.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-# requires all of the provider files in the providers folder
-#   which then allows the providers to be registered
-Dir['omni_exchange/providers/*.rb'].each do |file|
-  require_relative file
-end
+require 'omni_exchange/provider'
+# in order to make sure that all API data providers are registered correctly,
+#   all of the provider files in the providers folder must be required
+require 'omni_exchange/providers/open_exchange_rates'
+require 'omni_exchange/providers/xe'
 require 'omni_exchange/version'
 require 'omni_exchange/configuration'
+require 'omni_exchange/error'
 require 'faraday'
+require 'money'
 require 'json'
 require 'bigdecimal/util'
 
@@ -32,8 +34,9 @@ module OmniExchange
 
   module_function
 
-  # returns the amount of money in one country's currency when exchanged from an amount of money of another country's
-  #   currency using exchange rates data from API providers
+  # returns foreign exchange data including the amount of money in one country's currency when exchanged from an
+  #   amount of money of another country's currency using exchange rates data from API providers, the exchange
+  #   rate used to calculate that amount, and the API provider that supplied that rate.
   #
   # @param amount: [Integer, #to_d] the amount to exchange (in cents, if applicable to the currency). ie. 1, 10, 100
   # @param base_currency: [String] the ISO Currency Code of the currency that you're exchanging from. ie. "USD", "JPY"
@@ -41,11 +44,24 @@ module OmniExchange
   # @param providers: [Array] an array of symbols of the providers that will be used to get exchange rates API
   #   data. The symbols must be found in the @providers hash in the Provider class (lib/omni_exchange/provider.rb).
   #   ie. xe:, :open_exchange_rates
-  # @return [BigDecimal] the amount of the base currency exchanged to the target currency using an exchange rate
+  # @return [Hash] If all of the providers in the providers hash fail to retrieve data, or if one of the currencies
+  #   is not valid, an exception is raised.
+  #   * :converted_amount [BigDecimal] the amount of money exchanged from the base currency to the target
+  #       currency as a BigDecimal for precice calculation. ie. 1, 10, 100
+  #   * :exchange_rate [BigDecimal] the rate used to calculate the converted_amount as a BigDecimal. ie. 0.95211e1
+  #   * :provider_class [Class] the provider class that supplied the exchange_rate data. ie. OmniExchange::Xe
+  #the amount of the base currency exchanged to the target currency using an exchange rate
   #   provided by one of the data providers in the providers hash. The final amount is returned as a BigDecimal
-  #   for precise calculation. If all of the providers in the providers hash fail to retrieve data,
-  #   an exception is raised.
-  def exchange_currency(amount:, base_currency:, target_currency:, providers:)
+  #   for precise calculation. If all of the providers in the providers hash fail to retrieve data, an exception is raised.
+  def get_fx_data(amount:, base_currency:, target_currency:, providers:)
+    # if one of the currencies is not valid (ie. 'fake_crypto'), an exception is raised.
+    begin
+      Money::Currency.wrap(base_currency)
+      Money::Currency.wrap(target_currency)
+    rescue Money::Currency::UnknownCurrency => exception
+      raise OmniExchange::UnknownCurrency, "#{exception}"
+    end
+
     error_messages = []
 
     # Make sure all providers passed exist. If not, a LoadError is raise and not rescued
@@ -54,13 +70,15 @@ module OmniExchange
     # Gracefully hit each provider and fail-over to the next one
     provider_classes.each do |klass|
       rate = klass.get_exchange_rate(base_currency: base_currency, target_currency: target_currency)
-      
-      return rate * amount.to_d
+
+      exchanged_amount = rate.to_d * amount.to_d
+
+      return { converted_amount: exchanged_amount, exchange_rate: rate, provider_class: klass }
     rescue Faraday::Error, Faraday::ConnectionFailed => e
       error_messages << e.inspect
     end
     
-    raise "Failed to load #{base_currency}->#{target_currency}:\n#{exception_messages.join("\n")}"
+    raise OmniExchange::HttpError, "Failed to load #{base_currency}->#{target_currency}:\n#{error_messages.join("\n")}"
   end
 end
 # rubocop:enable Lint/Syntax

data/omni_exchange.gemspec

@@ -8,17 +8,17 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Yun Chung']
   spec.email         = ['yunseok_chung@degica.com']
 
-  spec.summary       = 'Write a short summary, because RubyGems requires one.'
-  spec.description   = 'Write a longer description or delete this line.'
+  spec.summary       = 'OmniExchange converts currencies using up-to-the-minute foreign exchange rates.'
+  spec.description   = 'OmniExchange converts currencies using up-to-the-minute foreign exchange rates.'
   spec.homepage      = 'https://degica.com'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://degica.com'
-  spec.metadata['changelog_uri'] = 'https://degica.com'
+  spec.metadata['homepage_uri'] = 'https://degica.com'
+  spec.metadata['source_code_uri'] = 'https://github.com/degica/omni_exchange'
+  spec.metadata['changelog_uri'] = 'https://github.com/degica/omni_exchange'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
@@ -27,7 +27,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'faraday'
+  spec.add_dependency 'faraday', '0.17.4'
+  spec.add_dependency 'money', '~> 6.13.1'
 
   spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'pry'

metadata

@@ -1,29 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: omni_exchange
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Yun Chung
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-21 00:00:00.000000000 Z
+date: 2022-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.17.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.17.4
+- !ruby/object:Gem::Dependency
+  name: money
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.13.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.13.1
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +122,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Write a longer description or delete this line.
+description: OmniExchange converts currencies using up-to-the-minute foreign exchange
+  rates.
 email:
 - yunseok_chung@degica.com
 executables: []
@@ -131,7 +146,7 @@ files:
 - bin/setup
 - lib/omni_exchange.rb
 - lib/omni_exchange/configuration.rb
-- lib/omni_exchange/currency_data.json
+- lib/omni_exchange/error.rb
 - lib/omni_exchange/provider.rb
 - lib/omni_exchange/providers/open_exchange_rates.rb
 - lib/omni_exchange/providers/xe.rb
@@ -143,8 +158,8 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://degica.com
-  source_code_uri: https://degica.com
-  changelog_uri: https://degica.com
+  source_code_uri: https://github.com/degica/omni_exchange
+  changelog_uri: https://github.com/degica/omni_exchange
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -160,8 +175,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: OmniExchange converts currencies using up-to-the-minute foreign exchange
+  rates.
 test_files: []