Ruby Gem for Currency Conversion with Caching

Project roadmap

1. 01

   Create the gem

   ~1h

   Create the skeleton with bundle gem currency_converter (choosing RSpec for tests), add faraday as a dependency and webmock as a development dependency, and fill in the gemspec (summary, description, license and required Ruby version). Create a CurrencyConverter::Converter class and the gem's own error classes (UnknownCurrency, RatesUnavailable). Done when: bundle exec rake builds the gem.

2. 02

   Fetch the rates

   ~1.5h

   Write a RatesClient that uses a Faraday connection (with timeouts and a retry middleware for temporary errors) to fetch the latest rates for a base currency from a free API such as Frankfurter, parses the JSON, and returns the rates as BigDecimal values with the date. Turn network errors and bad responses into RatesUnavailable with a clear message. Done when: the client returns real rates, and failures raise the gem's error.

3. 03

   Cache the rates

   ~1.5h

   Cache the rates in a JSON file (in a configurable folder, by default the user's cache folder) with the time they were fetched. Use cached rates when they're less than an hour old (configurable), and fall back to older cached rates with a warning when the API fails. Write the cache atomically. Done when: a second conversion within an hour makes no request, and the API being down still works with a cache.

4. 04

   Implement convert

   ~1h

   Add convert(amount, from:, to:) that validates the currency codes (3 letters, and present in the rates), converts through the base currency with BigDecimal, and rounds to 2 decimals by default (configurable). Also add rate(from:, to:) and supported_currencies. Converting a currency to itself needs no request. Done when: conversions are exact and match manual calculations.

5. 05

   Write specs and docs

   ~1.5h

   Write RSpec tests with WebMock stubbing the API: fetching and parsing, caching (fresh, stale and missing cache), fallback when the API fails, unknown currencies, rounding, and same-currency conversion. Document installation, usage examples, configuration and errors in README.md, with YARD comments on the public methods. Done when: bundle exec rspec passes, and README.md explains how to use the gem.

Resources

• DocsBundler: creating a gem
• DocsFaraday documentation
• DocsFrankfurter exchange rate API
• DocsRuby documentation: BigDecimal
• DocsWebMock