omni_exchange 0.1.0

data/lib/omni_exchange/provider.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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
+    #   file in the lib/omni_exchange/providers folder becomes required.
+    #
+    # @param provider_name [Symbol] the name of the exchange rate API data provider. ie. :xe, :open_exchange_rates
+    # @param provider_module [Class] the class of the provider. ie. OmniExchange::Xe, OmniExchange::OpenExchangeRates
+    def self.register_provider(provider_name, provider_module)
+      @providers[provider_name] = provider_module
+    end
+
+    # This method is called in the .exchange_currency method. It returns the provider that is requested if the provider
+    #   is registered in the @providers hash. Once loaded, class methods (such as .get_exchange_rate) can be called on
+    #   the provider. However, if the provider is unregistered, a LoadError is raised.
+    #
+    # @param provider_name [Symbol] the name of the exchange rate API provider that is to be loaded. ie. :xe
+    # @return [Class] the provider is returned if it has been registered properly in the @providers hash. Otherwise,
+    #   a LoadError exception is raised
+    def self.load_provider(provider_name)
+      provider = @providers[provider_name]
+      return provider if provider
+
+      raise(LoadError.new, "#{provider_name} did not load properly as a provider")
+    end
+
+    # a method that gives access to the @providers hash and the providers registered in it
+    def self.all
+      @providers
+    end
+
+    # Each provider class should inherit from Provider and have a .get_exchange_rates method. If a provider class
+    #   doesn't have a .get_exchange_rates method, the method below will be called and an error will be raised.
+    def self.get_exchange_rate
+      raise 'method not implemented...'
+    end
+
+    # 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.
+    #
+    # @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
+    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']
+    end
+  end
+end

data/lib/omni_exchange/providers/open_exchange_rates.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'omni_exchange'
+
+module OmniExchange
+  class OpenExchangeRates < Provider
+    ENDPOINT_URL = 'https://openexchangerates.org/api/latest.json'
+
+    # 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 Open Exchange Rate's API.
+    #   This method is called in the OmniExchange.exchange_currency method.
+    #
+    # @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"
+    # @ return [BigDecimal] an exchange rate is returned as a BigDecimal for precise calculation since this exchange
+    #   rate will be used to calculate an convert an exchange of currencies. However, an exception will be raised
+    #   if there is a timeout while connecting to xe.com or a timeout while reading Open Exchange Rate's API.
+    def self.get_exchange_rate(base_currency:, target_currency:)
+      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
+
+      begin
+        response = api.get do |req|
+          req.url "?app_id=#{app_id}&base=#{base_currency}"
+          req.options.timeout = config[:read_timeout] || OmniExchange::Configuration::DEFAULT_READ_TIMEOUT
+          req.options.open_timeout = config[:connect_timeout] || OmniExchange::Configuration::DEFAULT_CONNECTION_TIMEOUT
+        end
+      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 * currency_unit
+    end
+
+    # when this file is required at the top of lib/omni_exchange.rb, this method call is run and allows
+    #   OmniExchange::OpenExchangeRates to be registered in @providers.
+    OmniExchange::Provider.register_provider(:open_exchange_rates, self)
+  end
+end

data/lib/omni_exchange/providers/xe.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'omni_exchange'
+
+module OmniExchange
+  class Xe < Provider
+    ENDPOINT_URL = 'https://xecdapi.xe.com/'
+
+    # 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 xe.com's API.
+    #   This method is called in the OmniExchange.exchange_currency method.
+    #
+    # @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"
+    # @ return [BigDecimal] an exchange rate is returned as a BigDecimal for precise calculation since this exchange
+    #   rate will be used to calculate an convert an exchange of currencies. However, an exception will be raised
+    #   if there is a timeout while connecting to xe.com or a timeout while reading xe.com's API.
+    def self.get_exchange_rate(base_currency:, target_currency:)
+      config = OmniExchange.configuration.provider_config[:xe]
+      api_id = config[:api_id]
+      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 }
+      end
+
+      begin
+        response = api.get do |req|
+          req.url "v1/convert_from.json/?from=#{base_currency}&to=#{target_currency}&amount=#{currency_unit}"
+          req.options.timeout = config[:read_timeout] || OmniExchange::Configuration::DEFAULT_READ_TIMEOUT
+          req.options.open_timeout = config[:connect_timeout] || OmniExchange::Configuration::DEFAULT_CONNECTION_TIMEOUT
+        end
+      rescue Faraday::Error, Faraday::ConnectionFailed => e
+        raise e.class, 'xe.com has timed out.'
+      end
+
+      response.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
+    #   OmniExchange::Xe to be registered in @providers.
+    OmniExchange::Provider.register_provider(:xe, self)
+  end
+end

data/lib/omni_exchange/version.rb

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

data/lib/omni_exchange.rb

@@ -0,0 +1,66 @@
+# 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/version'
+require 'omni_exchange/configuration'
+require 'faraday'
+require 'json'
+require 'bigdecimal/util'
+
+# rubocop:disable Lint/Syntax
+module OmniExchange
+  class Error < StandardError; end
+
+  # the configuration instance variable is set to the module scope
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||= OmniExchange::Configuration.new
+  end
+
+  # This method allows you to call OmniExchange.configure with a block that creates a new
+  #   instance of OmniExchange::Configuration
+  def self.configure
+    yield(configuration)
+  end
+
+  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
+  #
+  # @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"
+  # @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 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
+    end
+    
+    raise "Failed to load #{base_currency}->#{target_currency}:\n#{exception_messages.join("\n")}"
+  end
+end
+# rubocop:enable Lint/Syntax

data/omni_exchange.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/omni_exchange/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'omni_exchange'
+  spec.version       = OmniExchange::VERSION
+  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.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.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday'
+
+  spec.add_development_dependency 'dotenv'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.80'
+  spec.add_development_dependency 'vcr'
+end

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification
+name: omni_exchange
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yun Chung
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.80'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.80'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Write a longer description or delete this line.
+email:
+- yunseok_chung@degica.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/omni_exchange.rb
+- lib/omni_exchange/configuration.rb
+- lib/omni_exchange/currency_data.json
+- lib/omni_exchange/provider.rb
+- lib/omni_exchange/providers/open_exchange_rates.rb
+- lib/omni_exchange/providers/xe.rb
+- lib/omni_exchange/version.rb
+- omni_exchange.gemspec
+homepage: https://degica.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://degica.com
+  source_code_uri: https://degica.com
+  changelog_uri: https://degica.com
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Write a short summary, because RubyGems requires one.
+test_files: []