Money

v2.0.1

Money

Money v2.0.1 Money.ExchangeRates behaviour View Source

Implements a behaviour and functions to retrieve exchange rates from an exchange rate service.

Configuration for the exchange rate service is defined in a Money.ExchangeRates.Config struct. A default configuration is returned by Money.ExchangeRates.default_config/0.

The default configuration is:

config :ex_money,
  exchange_rate_service: false,
  exchange_rates_retrieve_every: 300_000,
  api_module: Money.ExchangeRates.OpenExchangeRates,
  callback_module: Money.ExchangeRates.Callback,
  preload_historic_rates: nil
  log_failure: :warn,
  log_info: :info,
  log_success: nil

These keys are are defined as follows:

  • :exchange_rate_service is a boolean that determines whether to automatically start the exchange rate retrieval service. The default it false.

  • :exchange_rates_retrieve_every defines how often the exchange rates are retrieved in milliseconds. The default is 5 minutes (300,000 milliseconds)

  • :api_module identifies the module that does the retrieval of exchange rates. This is any module that implements the Money.ExchangeRates behaviour. The default is Money.ExchangeRates.OpenExchangeRates

  • :callback_module defines a module that follows the Money.ExchangeRates.Callback behaviour whereby the function rates_retrieved/2 is invoked after every successful retrieval of exchange rates. The default is Money.ExchangeRates.Callback.

  • :preload_historic_rates defines a date or a date range, that will be requested when the exchange rate service starts up. The date or date range should be specified as either a Date.t or a Date.Range.t or a tuple of {Date.t, Date.t} representing the from and to dates for the rates to be retrieved. The default is nil meaning no historic rates are preloaded.

  • :log_failure defines the log level at which api retrieval errors are logged. The default is :warn

  • :log_success defines the log level at which successful api retrieval notifications are logged. The default is nil which means no logging.

  • :log_info defines the log level at which service startup messages are logged. The default is :info.

  • :retriever_options is available for exchange rate retriever module developers as a place to add retriever-specific configuration information. This information should be added in the init/1 callback in the retriever module. See Money.ExchangeRates.OpenExchangeRates.init/1 for an example.

Keys can also be configured to retrieve values from environment variables. This lookup is done at runtime to facilitate deployment strategies. If the value of a configuration key is {:system, "some_string"} then “some_string” is interpreted as an environment variable name which is passed to System.get_env/2.

An example configuration might be:

config :ex_money,
  exchange_rate_service: {:system, "RATE_SERVICE"},
  exchange_rates_retrieve_every: {:system, "RETRIEVE_EVERY"},

Open Exchange Rates

If you plan to use the provided Open Exchange Rates module to retrieve exchange rates then you should also provide the additional configuration key for app_id:

config :ex_money,
  open_exchange_rates_app_id: "your_app_id"

or configure it via environment variable:

config :ex_money,
  open_exchange_rates_app_id: {:system, "OPEN_EXCHANGE_RATES_APP_ID"}

The default exchange rate retrieval module is provided in Money.ExchangeRates.OpenExchangeRates which can be used as a example to implement your own retrieval module for other services.

Managing the configuration at runtime

During exchange rate service startup, the function init/1 is called on the configuration exchange rate retrieval module. This module is expected to return an updated configuration allowing a developer to customise how the configuration is to be managed. See the implementation at Money.ExchangeRates.OpenExchangeRates.init/1 for an example.

Link to this section Summary

Functions

config()

Returns the configuration for ex_money including the configuration merged from the configured exchange rates retriever module

default_config()

Returns the default configuration for the exchange rates retriever

get_historic_rates(date, config \\ config())

Retrieves historic exchange rates from the configured exchange rate api module

get_latest_rates(config \\ config())

Retrieves the latest exchange rates from the configured exchange rate api module

historic_rates(date)

Return historic exchange rates

last_updated()

Return the timestamp of the last successful retrieval of exchange rates or {:error, reason} if no timestamp is known

latest_rates()

Return the latest exchange rates

latest_rates_available?()

Returns true if the latest exchange rates are available and false otherwise

retrieve_historic(date)

Forces retrieval of historic exchange rates for a single date

retrieve_historic(from, to)

Forces retrieval of historic exchange rates for a range of dates

retrieve_latest()

Forces retrieval of the latest exchange rates

Callbacks

get_historic_rates(arg0, config)

Invoked to return the historic exchange rates from the configured exchange rate retrieval service

get_latest_rates(config)

Invoked to return the latest exchange rates from the configured exchange rate retrieval service

init(config)

Given the default configuration, returns an updated configuration at runtime during exchange rates service startup

Link to this section Functions

Link to this function config() View Source

Returns the configuration for ex_money including the configuration merged from the configured exchange rates retriever module.

Link to this function default_config() View Source

Returns the default configuration for the exchange rates retriever.

Link to this function get_historic_rates(date, config \\ config()) View Source

Retrieves historic exchange rates from the configured exchange rate api module.

This call is the public api to retrieve results from an external api service or other mechanism implemented by an api module.

Link to this function get_latest_rates(config \\ config()) View Source

Retrieves the latest exchange rates from the configured exchange rate api module.

This call is the public api to retrieve results from an external api service or other mechanism implemented by an api module. This method is typically called periodically by Money.ExchangeRates.Retriever.handle_info/2 but can called at any time by other functions.

Link to this function historic_rates(date) View Source

Return historic exchange rates.

  • date is a date returned by Date.new/3 or any struct with the elements :year, :month and :day.

Returns:

  • {:ok, rates} if exchange rates are successfully retrieved. rates is a map of exchange rates.

  • {:error, reason} if no exchange rates can be returned.

Note; all dates are assumed to be in the Calendar.ISO calendar

This function looks up the historic exchange rates in a an ETS table called :exchange_rates. The actual retrieval of rates is requested through Money.ExchangeRates.retrieve_historic_rates/1.

Link to this function last_updated() View Source 
last_updated() ::
  {:ok, DateTime.t()} |
  {:error, {Exception.t(), binary()}}

Return the timestamp of the last successful retrieval of exchange rates or {:error, reason} if no timestamp is known.

Example 

Money.ExchangeRates.last_updated
#> {:ok,
 %DateTime{calendar: Calendar.ISO, day: 20, hour: 12, microsecond: {731942, 6},
  minute: 36, month: 11, second: 6, std_offset: 0, time_zone: "Etc/UTC",
  utc_offset: 0, year: 2016, zone_abbr: "UTC"}}
Link to this function latest_rates() View Source 
latest_rates() :: {:ok, Map.t()} | {:error, {Exception.t(), binary()}}

Return the latest exchange rates.

Returns:

  • {:ok, rates} if exchange rates are successfully retrieved. rates is a map of exchange rates.

  • {:error, reason} if no exchange rates can be returned.

This function looks up the latest exchange rates in a an ETS table called :exchange_rates. The actual retrieval of rates is requested through Money.ExchangeRates.retrieve_latest_rates/0.

Link to this function latest_rates_available?() View Source 
latest_rates_available?() :: boolean()

Returns true if the latest exchange rates are available and false otherwise.

Link to this function retrieve_historic(date) View Source

Forces retrieval of historic exchange rates for a single date

  • date is a date returned by Date.new/3 or any struct with the elements :year, :month and :day or

  • a Date.Range.t created by Date.range/2 that specifies a range of dates to retrieve

Returns:

  • :ok if exchange rates request is successfully sent.

  • {:error, reason} if the request cannot be send.

Sends a message ot the exchange rate retrieval worker to request historic rates for a specified date or range be retrieved and stored.

This function does not return exchange rates, for that see Money.ExchangeRates.latest_rates/0 or Money.ExchangeRates.historic_rates/1.

Link to this function retrieve_historic(from, to) View Source

Forces retrieval of historic exchange rates for a range of dates

  • from is a date returned by Date.new/3 or any struct with the elements :year, :month and :day.

  • to is a date returned by Date.new/3 or any struct with the elements :year, :month and :day.

Returns:

  • :ok if exchange rates request is successfully sent.

  • {:error, reason} if the request cannot be send.

Sends a message to the exchange rate retrieval worker for each date in the range from..to to request historic rates be retrieved and stored.

This function does not return exchange rates, for that see Money.ExchangeRates.latest_rates/0 or Money.ExchangeRates.historic_rates/1.

Link to this function retrieve_latest() View Source

Forces retrieval of the latest exchange rates

Sends a message ot the exchange rate retrieval worker to request current rates be retrieved and stored.

Returns:

  • :ok if exchange rates request is successfully sent.

  • {:error, reason} if the request cannot be send.

This function does not return exchange rates, for that see Money.ExchangeRates.latest_rates/0 or Money.ExchangeRates.historic_rates/1.

Link to this section Callbacks

Link to this callback get_historic_rates(arg0, config) View Source 
get_historic_rates(Date.t(), config :: Money.Config.t()) ::
  {:ok, Map.t()} |
  {:error, binary()}

Invoked to return the historic exchange rates from the configured exchange rate retrieval service.

  • config is an %Money.ExchangeRataes.Config{} struct

Returns {:ok, map_of_historic_rates} or {:error, reason}

Link to this callback get_latest_rates(config) View Source 
get_latest_rates(config :: Money.Config.t()) ::
  {:ok, Map.t()} |
  {:error, binary()}

Invoked to return the latest exchange rates from the configured exchange rate retrieval service.

  • config is an %Money.ExchangeRataes.Config{} struct

Returns {:ok, map_of_rates} or {:error, reason}

Link to this callback init(config) View Source (optional) 
init(config :: Money.Config.t()) :: Money.Config.t()

Given the default configuration, returns an updated configuration at runtime during exchange rates service startup.

This callback is optional. If the callback is not defined, the default configuration returned by Money.ExchangeRates.default_config/0 is used.

The callback is expected to return a %Money.ExchangeRates.Config{} struct which may have been updated. The configuration key :retriever_options is available for any service-specific configuration.