omni_exchange 0.2.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f688c61226d02342f3c6e2730982b059d46cf6033fa61f822477d332bf21fc6b
-  data.tar.gz: 19d3020b4d6146634d6931e8ac72247e5d17072156bca230a75307c398b26c4c
+  metadata.gz: 79069dcd87cf3788896dbc2093d114028b94592743a5fea03559cfce974b4d5c
+  data.tar.gz: 03a24de2dcfe6dca9ee1c0532e40b8bab6addbc14c9e4863ef644789a0a24adb
 SHA512:
-  metadata.gz: 44b9222aa670f9495d713b62b3a01115388c68e820cd24d699beab5b8df9a80a084a3f3613f9edac17c2e0e4e5fa642cd0bab6b466b87b56e25ee8b6ae88387e
-  data.tar.gz: 704c9d03570dec02e8115bf224a354e1bcea4a85574167b826cbb33b9d7dccce7c88c404d18d76d58291b4c74709624f6cd888353e05ca0b12e86c2dac6709b6
+  metadata.gz: bb380807a18d884f6ebef61b911e9a5301f6704577a15b8b4fc75cc11a4e0337ee1c911ea01c9a8269f919f6df62f86225cc9270bf24c8cad753eed0cefa8e2d
+  data.tar.gz: f0909dabbacc96857512b405cc590431ca9df724f622d0e59d589c62e2856e2d6193e992370f4a06d52df2eff7c3f6d1acca1741f5d6c12c9be20c9736b6eef0

data/.gitignore

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

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2022-06-24 08:14:59 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
@@ -15,7 +15,7 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods.
 # ExcludedMethods: refine
 Metrics/BlockLength:
-  Max: 26
+  Max: 27
 
 # Offense count: 1
 Naming/AccessorMethodName:

data/Gemfile.lock

@@ -1,19 +1,25 @@
 PATH
   remote: .
   specs:
-    omni_exchange (0.2.0)
+    omni_exchange (1.2.0)
       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 (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)

data/README.md

@@ -2,7 +2,7 @@
 
 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 from another API data source.
+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
 
@@ -46,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]
 
-[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.
+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), 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
 
 ```
 
@@ -75,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/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).
+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
 

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,15 @@
+# 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
+
+  # A custom error for exceeding the monthly request limit for xe.com
+  class XeMonthlyLimit < 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

@@ -33,9 +33,9 @@ module OmniExchange
 
       exchange_rate = JSON.parse(response.body, symbolize_names: true)[:rates][target_currency.to_sym].to_d
 
-      currency_unit = get_currency_unit(base_currency)
+      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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/AbcSize
 require 'omni_exchange'
 
 module OmniExchange
@@ -36,7 +37,11 @@ module OmniExchange
         raise e.class, 'xe.com has timed out.'
       end
 
-      JSON.parse(response.body, symbolize_names: true)[:to][0][:mid].to_d
+      body = JSON.parse(response.body, symbolize_names: true)
+
+      raise OmniExchange::XeMonthlyLimit, 'Xe.com monthly limit has been exceeded' if body[:code] == 3
+
+      body[: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
@@ -44,3 +49,4 @@ module OmniExchange
     OmniExchange::Provider.register_provider(:xe, self)
   end
 end
+# rubocop:enable Metrics/AbcSize

data/lib/omni_exchange/version.rb

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

data/lib/omni_exchange.rb

@@ -7,7 +7,9 @@ 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,41 +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:)
-    error_messages = []
-
-    # Make sure all providers passed exist. If not, a LoadError is raise and not rescued
-    provider_classes = providers.map { |p| OmniExchange::Provider.load_provider(p) }
-
-    # 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
-    rescue Faraday::Error, Faraday::ConnectionFailed => e
-      error_messages << e.inspect
+  #   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
-    
-    raise "Failed to load #{base_currency}->#{target_currency}:\n#{exception_messages.join("\n")}"
-  end
 
-  # This method returns the exchange rate, the rate at which the smallest unit of one currency (the base currency)
-  #   will be exchanged for another currency (the target currency), from API providers 
-  #
-  # @param base_currency: [String] the ISO Currency Code of the currency that you're exchanging from. ie. "USD", "JPY"
-  # @param target_currency: [String] the ISO Currency Code of the currency that you're exchanging to. ie. "EUR", "KRW"
-  # @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
-  #   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 get_exchange_rate(base_currency:, target_currency:, providers:)
     error_messages = []
 
     # Make sure all providers passed exist. If not, a LoadError is raise and not rescued
@@ -84,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
-    rescue Faraday::Error, Faraday::ConnectionFailed => e
+
+      exchanged_amount = rate.to_d * amount.to_d
+
+      return { converted_amount: exchanged_amount, exchange_rate: rate, provider_class: klass }
+    rescue Faraday::Error, Faraday::ConnectionFailed, OmniExchange::XeMonthlyLimit => 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

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omni_exchange
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Yun Chung
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-27 00:00:00.000000000 Z
+date: 2022-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         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
@@ -132,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