timeprice 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc65e20b859501552fbc5b53a7d6d3f833159d941ed5afc52bd1e9b51153d0fe
-  data.tar.gz: 93f795ee7466123a98dd56d6ef202d19de8e2e68ea0588cfcfd6a1172142d681
+  metadata.gz: 160a9501bc1004df45cd71202f3ae07711068adade2118cfe4605a2e92d92f6f
+  data.tar.gz: 68ea05103245f2bb1fb02d701fd5db6e1bb814a2b47d20f6eb9011d94a57b269
 SHA512:
-  metadata.gz: d94e236e90f83d00a5e9ce871f74353aaf67245649ad7c3d21f69515b06049fecf4170844b4decea5533a3a82a9ceb444a5906f868535181ce0f13ce684119a5
-  data.tar.gz: f456c4a3b346031d6d69c2a55de77177022c9cabe7e1f656a8221dad767427786bc12d2838a81e67c514d6d9b86c76a33151f8f58095b672960f0f3b3f5c0bae
+  metadata.gz: fdddfd9cbcf4cefad6ee73134eb8ef3e5ad5b863aa8d5a78fa789b8890cefec0690cf3c1022f1b596c2bdeaf6f9a8f1122d8ff6ef9adfb7dd393e0aa9346afb6
+  data.tar.gz: 4342d02e30f4058f6e7a98eedab2fd0fa54b14031f061bf4d17b093d02f6a1e5cd16ea1f994e7d868cc893fe29119bdae1a398724665f14502c9b135ee1396b0

data/CHANGELOG.md

@@ -5,7 +5,33 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.1.1] - 2026-05-11
+## [0.2.0] - 2026-05-11
+
+### Added
+- `Timeprice::Point` value object for compare inputs; `Point.coerce` accepts `Point` instances or 2-tuples in either `[currency, date]` or `[date, currency]` order.
+- `Timeprice::Supported` module — canonical home for `COUNTRIES`, `CURRENCIES`, and the bidirectional currency↔country map. Replaces the duplicated maps in `Compare` and the CLI's `InflationResult` monkey-patch.
+- `Sources::Base` class extracted from the CPI fetchers; `BLS`, `ONS`, and `Eurostat` now subclass it and implement only `fetch` returning `[monthly, annual]`. The drift-check, rebase, merge, write, and summary-log flow is shared.
+- Per-fetcher GitHub Actions `::warning file=…,title=…::` annotations in `scripts/update_data.rb`, so individual fetcher failures show up on the workflow run with a link to the responsible source file.
+- README "Using from Rails / Rake" section covering service objects, Sidekiq, Rake tasks, and `TIMEPRICE_DATA_ROOT`.
+- YARD documentation on the public API (`Timeprice.{inflation,exchange,compare}`, `Inflation`, `Exchange`, `Compare`, `DataLoader`, `Sources`, error classes, `Supported`, `Point`).
+
+### Changed
+- `SUPPORTED_COUNTRIES` / `SUPPORTED_CURRENCIES` are now thin aliases for `Supported::COUNTRIES` / `Supported::CURRENCIES`; existing consumers keep working unchanged.
+- `Compare::CURRENCY_TO_COUNTRY` is now an alias for `Supported::CURRENCY_TO_COUNTRY`.
+
+## [0.1.2] - 2026-05-11
+
+### Added
+- RuboCop with `rubocop-rake` + `rubocop-rspec`, wired into Rake (`rake default` runs spec + rubocop) and CI (separate `RuboCop` job alongside `RSpec`).
+
+### Changed
+- `DataLoader.load_cpi` now distinguishes between "country isn't supported" (`UnsupportedCountry`) and "data file is missing on disk" (`DataNotFound` with the path the loader looked at). Previously both surfaced as `UnsupportedCountry`, masking install / `TIMEPRICE_DATA_ROOT` misconfigurations.
+- `Timeprice.exchange` now rejects invalid calendar dates (e.g. `2021-02-29`) with `ArgumentError` instead of leaking a `Date::Error`. Honors the public error contract.
+- Trimmed `ZERO_DECIMAL_CURRENCIES` to currencies actually supported by the gem (JPY, VND). Removed aspirational entries (KRW, IDR, HUF, CLP).
+- Inline source comments now reference README sections (`README.md "Compare semantics"`) instead of `PLAN.md` (which is intentionally not shipped in the gem).
+- `CONTRIBUTING.md` updated to match the single-Ruby CI; both `rspec` and `rubocop` must be green.
+
+
 
 ### Changed
 - CLI output formatting: currency-aware decimals (no `.0000` on JPY/VND), magnitude-aware FX rate precision (no `91.180000` for a 91.18 rate).

data/README.md

@@ -155,6 +155,91 @@ inflated = Timeprice.inflation(amount: 100, from: "2010", to: "2024", country: "
 converted = Timeprice.exchange(amount: inflated, from: "USD", to: "VND", date: "2024-06-30").amount
 ```
 
+## Using from Rails / Rake
+
+`timeprice` is a plain Ruby library — no Railtie, no engine, no autoload magic. It works
+the same way as `BigDecimal` or `JSON`: require it once, call the module functions.
+
+### In a Rails app
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "timeprice", "~> 0.1"
+```
+
+Then call it directly from controllers, jobs, presenters, or service objects. The library
+is thread-safe (data files are loaded once and cached as frozen hashes), so it's safe to
+call from threaded servers (Puma) and Sidekiq workers:
+
+```ruby
+# app/services/historical_price.rb
+class HistoricalPrice
+  def self.in_today_dollars(amount, year)
+    Timeprice.inflation(
+      amount: amount,
+      from: year.to_s,
+      to: Date.current.strftime("%Y-%m"),
+      country: "US"
+    ).amount
+  end
+end
+```
+
+Errors all inherit from `Timeprice::Error`, so a single rescue covers everything:
+
+```ruby
+rescue Timeprice::Error => e
+  Rails.logger.warn("timeprice lookup failed: #{e.message}")
+  nil
+end
+```
+
+Result objects respond to `#to_h`, so they serialize cleanly in JSON APIs:
+
+```ruby
+def show
+  render json: Timeprice.exchange(amount: 100, from: "USD", to: "EUR", date: params[:date]).to_h
+end
+```
+
+### In a Rake task
+
+```ruby
+# lib/tasks/inflation.rake
+require "timeprice"
+
+namespace :inflation do
+  desc "Print 1990→today inflation for the supported countries"
+  task :report do
+    today = Date.today.strftime("%Y-%m")
+    %w[US UK EU JP VN].each do |c|
+      r = Timeprice.inflation(amount: 100, from: "1990", to: today, country: c)
+      puts "#{c}: 100 in 1990 → #{r.amount.round(2)} in #{today} (#{r.granularity})"
+    end
+  end
+end
+```
+
+### Configuring the data root
+
+By default the gem reads from its bundled `data/` directory. To point at a different
+checkout (useful for testing a new data refresh before releasing it), set
+`TIMEPRICE_DATA_ROOT`:
+
+```bash
+TIMEPRICE_DATA_ROOT=/path/to/timeprice/data bundle exec rake inflation:report
+```
+
+Or programmatically:
+
+```ruby
+Timeprice::DataLoader.data_root = "/path/to/timeprice/data"
+```
+
+Reassigning `data_root` clears the in-memory cache, so it's safe to call between requests
+in development.
+
 ## Data sources & attribution
 
 `timeprice` redistributes data from several public sources. Each is governed by its own

data/lib/timeprice/cli.rb

@@ -73,7 +73,7 @@ module Timeprice
         say JSON.generate(list)
       else
         list.each do |s|
-          say "#{s[:name]}"
+          say s[:name].to_s
           say "  id:           #{s[:id]}"
           say "  license:      #{s[:license]}"
           say "  license_url:  #{s[:license_url]}"
@@ -95,7 +95,7 @@ module Timeprice
 
     no_commands do
       # Currencies with no minor unit — render whole numbers, no decimals.
-      ZERO_DECIMAL_CURRENCIES = %w[JPY VND KRW IDR HUF CLP].freeze
+      ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
 
       def with_error_handling
         yield
@@ -109,6 +109,7 @@ module Timeprice
 
       def parse_compare_token(token, label:)
         raise ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
+
         parts = token.strip.split(/\s+/)
         unless parts.size == 2
           raise ArgumentError,
@@ -142,6 +143,7 @@ module Timeprice
       # answer actually used annual data — that's where users want a heads-up.
       def granularity_suffix(granularity)
         return "" if granularity == :monthly
+
         " (granularity: #{granularity})"
       end
 
@@ -201,12 +203,8 @@ end
 # bloating the value object — the result doesn't carry currency, only country.
 module Timeprice
   class InflationResult
-    COUNTRY_TO_CURRENCY = {
-      "US" => "USD", "UK" => "GBP", "EU" => "EUR", "JP" => "JPY", "VN" => "VND"
-    }.freeze
-
     def country_currency_label
-      COUNTRY_TO_CURRENCY[country.to_s.upcase] || country.to_s.upcase
+      Supported.currency_for_country(country) || country.to_s.upcase
     end
   end
 end

data/lib/timeprice/compare.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "supported"
+require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
 
@@ -16,7 +18,7 @@ module Timeprice
   # Compare combines FX and inflation across two (currency, date) points.
   #
   # CONVENTION (critical): convert at SOURCE date first, then inflate in
-  # destination currency. See PLAN.md §2 last bullet and §7.
+  # destination currency. See README.md "Compare semantics" section.
   #
   # This preserves purchasing-power equivalence in the destination economy.
   # The naive alternative (inflate in source currency first, then convert at
@@ -26,29 +28,22 @@ module Timeprice
   # If a future refactor flips the order, the regression test in
   # spec/timeprice/compare_spec.rb will fail.
   module Compare
-    # Map ISO currency → CPI country code.
-    CURRENCY_TO_COUNTRY = {
-      "USD" => "US",
-      "GBP" => "UK",
-      "EUR" => "EU",
-      "JPY" => "JP",
-      "VND" => "VN"
-    }.freeze
+    # Map ISO currency → CPI country code. Kept as a back-compat alias;
+    # the canonical map lives in {Supported::CURRENCY_TO_COUNTRY}.
+    CURRENCY_TO_COUNTRY = Supported::CURRENCY_TO_COUNTRY
 
     module_function
 
-    # amount: Numeric
-    # from:   [currency, date_or_year] e.g. ["USD", "2010"] or ["USD", "2010-06"]
-    # to:     [currency, date_or_year]
+    # Compare an amount across two (currency, date) points.
+    #
+    # @param amount [Numeric]
+    # @param from   [Timeprice::Point, Array(String, String)] source point;
+    #   accepts a {Point} or a 2-tuple like `["USD", "2010"]` or `["USD", "2010-06"]`
+    # @param to     [Timeprice::Point, Array(String, String)] destination point
+    # @return [CompareResult]
+    # @raise [UnsupportedCurrency] if either currency is not in {Supported::CURRENCIES}
     def run(amount:, from:, to:)
-      from_currency, from_date = from
-      to_currency,   to_date   = to
-      from_currency = from_currency.to_s.upcase
-      to_currency   = to_currency.to_s.upcase
-
-      to_country = CURRENCY_TO_COUNTRY[to_currency] ||
-                   (raise UnsupportedCurrency, to_currency)
-      CURRENCY_TO_COUNTRY[from_currency] || (raise UnsupportedCurrency, from_currency)
+      from_currency, from_date, to_currency, to_date, to_country = resolve_points(from, to)
 
       # Step 1: convert at source date into destination currency.
       fx_date = normalize_fx_date(from_date)
@@ -78,12 +73,25 @@ module Timeprice
         to_date: to_date.to_s,
         country: to_country,
         fx_rate: fx_result.rate,
-        cpi_ratio: infl.to_index.to_f / infl.from_index.to_f,
+        cpi_ratio: infl.to_index.to_f / infl.from_index,
         converted_amount: converted,
         granularity: infl.granularity
       )
     end
 
+    # Coerce both points and resolve to_country. Returns a 5-element tuple.
+    def resolve_points(from, to)
+      from_point = Point.coerce(from)
+      to_point   = Point.coerce(to)
+      from_currency = from_point.currency
+      to_currency   = to_point.currency
+      to_country = Supported.country_for_currency(to_currency) ||
+                   (raise UnsupportedCurrency, to_currency)
+      Supported.country_for_currency(from_currency) || (raise UnsupportedCurrency, from_currency)
+
+      [from_currency, from_point.date, to_currency, to_point.date, to_country]
+    end
+
     # If the user gave a year like "2010", anchor FX to mid-year (2010-06-30).
     # If they gave "YYYY-MM", anchor to the 15th. Full dates pass through.
     def normalize_fx_date(date)

data/lib/timeprice/data_loader.rb

@@ -4,42 +4,69 @@ require "json"
 require_relative "errors"
 
 module Timeprice
+  # Loads and caches the bundled JSON data files. Override the search root
+  # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
+  # {DataLoader.data_root=}.
   module DataLoader
     SUPPORTED_SCHEMA_VERSION = 1
 
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
+      # @return [String] absolute path to the directory containing `cpi/` and `fx/`
       def data_root
         ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
       end
 
+      # Override the data root and clear caches. Mostly useful in tests.
+      # @param path [String]
+      # @return [void]
       def data_root=(path)
         @data_root = path
         clear_cache!
       end
 
+      # Drop in-memory caches of parsed data files.
+      # @return [void]
       def clear_cache!
         @cpi_cache = {}
         @fx_cache = {}
       end
 
+      # Load the CPI series for a supported country.
+      # @param country [String]
+      # @return [Hash] parsed JSON with "monthly" / "annual" / metadata keys
+      # @raise [UnsupportedCountry] if `country` is not in {Supported::COUNTRIES}
+      # @raise [DataNotFound]       if the file is missing
+      # @raise [UnsupportedSchemaVersion] if the file uses a future schema
       def load_cpi(country)
         @cpi_cache ||= {}
         key = country.to_s.downcase
+        code = country.to_s.upcase
         @cpi_cache[[data_root, key]] ||= begin
+          raise UnsupportedCountry, code unless SUPPORTED_COUNTRIES.include?(code)
+
           path = File.join(data_root, "cpi", "#{key}.json")
-          raise UnsupportedCountry, country.to_s.upcase unless File.exist?(path)
+          unless File.exist?(path)
+            raise DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
+                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+          end
+
           parse_with_schema(path)
         end
       end
 
+      # Load the FX rates for a year.
+      # @param year [Integer, String]
+      # @return [Hash] parsed JSON with a "rates" map of date → currency → Float
+      # @raise [DataNotFound] if the per-year file is missing
       def load_fx_year(year)
         @fx_cache ||= {}
         key = year.to_i
         @fx_cache[[data_root, key]] ||= begin
           path = File.join(data_root, "fx", "usd", "#{key}.json")
           raise DataNotFound, "No FX data for year #{key}" unless File.exist?(path)
+
           parse_with_schema(path)
         end
       end
@@ -49,9 +76,8 @@ module Timeprice
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]
-        unless version == SUPPORTED_SCHEMA_VERSION
-          raise UnsupportedSchemaVersion.new(version, path)
-        end
+        raise UnsupportedSchemaVersion.new(version, path) unless version == SUPPORTED_SCHEMA_VERSION
+
         data
       end
     end

data/lib/timeprice/errors.rb

@@ -1,29 +1,33 @@
 # frozen_string_literal: true
 
+require_relative "supported"
+
 module Timeprice
+  # Base class for every error this library raises. Catch `Timeprice::Error`
+  # to handle anything the gem can throw at you.
   class Error < StandardError; end
 
-  SUPPORTED_COUNTRIES = %w[US UK EU JP VN].freeze
-  SUPPORTED_CURRENCIES = %w[USD GBP EUR JPY VND].freeze
-
+  # Raised when a country code is not in {Supported::COUNTRIES}.
   class UnsupportedCountry < Error
     attr_reader :country
 
     def initialize(country)
       @country = country
-      super("Unsupported country: #{country.inspect} (supported: #{SUPPORTED_COUNTRIES.join(", ")})")
+      super("Unsupported country: #{country.inspect} (supported: #{Supported::COUNTRIES.join(", ")})")
     end
   end
 
+  # Raised when a currency code is not in {Supported::CURRENCIES}.
   class UnsupportedCurrency < Error
     attr_reader :currency
 
     def initialize(currency)
       @currency = currency
-      super("Unsupported currency: #{currency.inspect} (supported: #{SUPPORTED_CURRENCIES.join(", ")})")
+      super("Unsupported currency: #{currency.inspect} (supported: #{Supported::CURRENCIES.join(", ")})")
     end
   end
 
+  # Raised when a requested date falls outside the bundled data range.
   class DateOutOfRange < Error
     attr_reader :date, :range
 
@@ -34,12 +38,15 @@ module Timeprice
     end
   end
 
+  # Raised when a CPI or FX lookup has no usable data point.
   class DataNotFound < Error
     def initialize(message = "Data not found")
       super
     end
   end
 
+  # Raised when a bundled data file declares a schema_version this gem
+  # doesn't know how to parse (forward-compat guard).
   class UnsupportedSchemaVersion < Error
     attr_reader :version, :path
 

data/lib/timeprice/exchange.rb

@@ -9,6 +9,10 @@ module Timeprice
     :amount, :original_amount, :from, :to, :date, :effective_date, :rate
   )
 
+  # Historical FX conversion using bundled per-year USD-base rate files.
+  # Handles identity (USD→USD), direct lookup, inverse, and triangulation
+  # through USD. Weekend/holiday dates fall back up to {MAX_FALLBACK_DAYS}
+  # days to the nearest prior trading day.
   module Exchange
     BASE = "USD"
     MAX_FALLBACK_DAYS = 7
@@ -16,12 +20,20 @@ module Timeprice
     module_function
 
     # Convert `amount` from currency `from` to currency `to` on `date`.
-    # date: "YYYY-MM-DD".
+    #
+    # @param amount [Numeric]
+    # @param from   [String] ISO 4217 source currency
+    # @param to     [String] ISO 4217 destination currency
+    # @param date   [String, Date] date as "YYYY-MM-DD" or a Date instance
+    # @return [ExchangeResult]
+    # @raise [UnsupportedCurrency] if `from` or `to` is not supported
+    # @raise [DataNotFound]        if no FX point exists within {MAX_FALLBACK_DAYS}
     def convert(amount:, from:, to:, date:)
       from = from.to_s.upcase
       to   = to.to_s.upcase
       raise UnsupportedCurrency, from unless SUPPORTED_CURRENCIES.include?(from)
       raise UnsupportedCurrency, to   unless SUPPORTED_CURRENCIES.include?(to)
+
       d = parse_date(date)
 
       rate, eff_date = resolve_rate(from, to, d)
@@ -77,8 +89,10 @@ module Timeprice
           end
         rates_for_day = year_data.dig("rates", candidate.to_s)
         next unless rates_for_day
+
         rate = rates_for_day[currency]
         next unless rate
+
         return [rate.to_f, candidate]
       end
       raise DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
@@ -91,7 +105,12 @@ module Timeprice
         unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
           raise ArgumentError, "Invalid date format: #{date.inspect} (use YYYY-MM-DD)"
         end
-        Date.parse(date)
+
+        begin
+          Date.parse(date)
+        rescue Date::Error
+          raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
+        end
       else
         raise ArgumentError, "Invalid date: #{date.inspect}"
       end

data/lib/timeprice/inflation.rb

@@ -16,18 +16,27 @@ module Timeprice
     :from_index, :to_index, :granularity
   )
 
+  # CPI-based inflation adjustment for the {Supported::COUNTRIES} list.
   module Inflation
     module_function
 
     # Adjust `amount` from date `from` to date `to` using country CPI.
     #
     # Dates accept "YYYY" or "YYYY-MM".
+    #
+    # @param amount  [Numeric]
+    # @param from    [String] source date ("YYYY" or "YYYY-MM")
+    # @param to      [String] target date ("YYYY" or "YYYY-MM")
+    # @param country [String] country code (see {Supported::COUNTRIES})
+    # @return [InflationResult]
+    # @raise [UnsupportedCountry] if `country` is not supported
+    # @raise [DataNotFound]       if no CPI data covers the requested period
     def adjust(amount:, from:, to:, country:)
       data = DataLoader.load_cpi(country)
       from_index, from_gran = lookup_index(data, from)
       to_index,   to_gran   = lookup_index(data, to)
 
-      ratio = to_index.to_f / from_index.to_f
+      ratio = to_index.to_f / from_index
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
@@ -41,6 +50,11 @@ module Timeprice
     end
 
     # Inflation rate as decimal (e.g. 0.42 = 42%).
+    #
+    # @param from    [String]
+    # @param to      [String]
+    # @param country [String]
+    # @return [Float] decimal rate (positive means inflation, negative deflation)
     def rate(from:, to:, country:)
       result = adjust(amount: 1.0, from: from, to: to, country: country)
       result.amount - 1.0
@@ -58,11 +72,10 @@ module Timeprice
           [monthly[key], :monthly]
         else
           year = key[0, 4]
-          if annual.key?(year)
-            [annual[year], :annual]
-          else
-            raise DataNotFound, missing_cpi_message(key, data, monthly, annual)
-          end
+          raise DataNotFound, missing_cpi_message(key, data, monthly, annual) unless annual.key?(year)
+
+          [annual[year], :annual]
+
         end
       when /\A\d{4}\z/
         if annual.key?(key)
@@ -70,6 +83,7 @@ module Timeprice
         else
           months = monthly.select { |k, _| k.start_with?("#{key}-") }
           raise DataNotFound, missing_cpi_message(key, data, monthly, annual) if months.empty?
+
           avg = months.values.sum.to_f / months.size
           [avg, :annual_from_monthly_avg]
         end
@@ -98,6 +112,7 @@ module Timeprice
     def merge_granularity(a, b)
       return :annual_from_monthly_avg if a == :annual_from_monthly_avg || b == :annual_from_monthly_avg
       return :annual if a == :annual || b == :annual
+
       :monthly
     end
   end

data/lib/timeprice/point.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # A (currency, date) pair used as input to {Timeprice.compare}.
+  #
+  # The library accepts either a Point or a 2-element array. Arrays may be
+  # ordered either way (`["USD", "2010"]` or `["2010", "USD"]`) — the year
+  # and currency are detected by shape. This mirrors what the CLI already
+  # tolerates and removes the only "which slot is which?" footgun.
+  #
+  # @example
+  #   Timeprice::Point.new(currency: "USD", date: "2010")
+  #   Timeprice::Point.coerce(["USD", "2010"])
+  #   Timeprice::Point.coerce(["2010", "USD"])
+  Point = Data.define(:currency, :date) do
+    # Coerce input into a Point. Accepts:
+    #   - {Point} (returned as-is)
+    #   - 2-element Array of [currency, date] in either order
+    #
+    # @param input [Point, Array]
+    # @return [Point]
+    # @raise [ArgumentError] if shape can't be recognised
+    def self.coerce(input)
+      return input if input.is_a?(Point)
+
+      unless input.is_a?(Array) && input.size == 2
+        raise ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
+      end
+
+      a, b = input.map(&:to_s)
+      currency = [a, b].find { |s| s.match?(/\A[A-Za-z]{3}\z/) }
+      date     = [a, b].find { |s| s.match?(/\A\d{4}(-\d{2}(-\d{2})?)?\z/) }
+
+      if currency.nil? || date.nil?
+        raise ArgumentError,
+              "Could not detect currency + date in #{input.inspect} " \
+              "(expected a 3-letter currency and a YYYY[-MM[-DD]] date)"
+      end
+
+      new(currency: currency.upcase, date: date)
+    end
+  end
+end

data/lib/timeprice/sources.rb

@@ -15,7 +15,7 @@ module Timeprice
         name: "U.S. Bureau of Labor Statistics — CPI-U (series CUUR0000SA0)",
         license: "U.S. Government work — public domain",
         license_url: "https://www.bls.gov/bls/linksite.htm",
-        attribution: "Data: U.S. Bureau of Labor Statistics"
+        attribution: "Data: U.S. Bureau of Labor Statistics",
       },
       {
         id: "uk_cpi",
@@ -24,7 +24,7 @@ module Timeprice
         name: "UK Office for National Statistics — CPI all-items (series D7BT)",
         license: "Open Government Licence v3.0",
         license_url: "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
-        attribution: "Contains public sector information licensed under the Open Government Licence v3.0"
+        attribution: "Contains public sector information licensed under the Open Government Licence v3.0",
       },
       {
         id: "eu_hicp",
@@ -33,7 +33,7 @@ module Timeprice
         name: "Eurostat — HICP prc_hicp_midx (Euro area, all items)",
         license: "Eurostat reuse policy (free reuse with attribution)",
         license_url: "https://ec.europa.eu/eurostat/about-us/policies/copyright",
-        attribution: "Source: Eurostat"
+        attribution: "Source: Eurostat",
       },
       {
         id: "jp_cpi",
@@ -42,7 +42,7 @@ module Timeprice
         name: "World Bank — FP.CPI.TOTL (annual, JP fallback)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "Source: World Bank, FP.CPI.TOTL"
+        attribution: "Source: World Bank, FP.CPI.TOTL",
       },
       {
         id: "vn_cpi",
@@ -51,7 +51,7 @@ module Timeprice
         name: "World Bank — FP.CPI.TOTL (annual)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "Source: World Bank, FP.CPI.TOTL"
+        attribution: "Source: World Bank, FP.CPI.TOTL",
       },
       {
         id: "fx_ecb",
@@ -60,7 +60,7 @@ module Timeprice
         name: "European Central Bank reference rates (via Frankfurter)",
         license: "ECB reference rates — free reuse",
         license_url: "https://www.ecb.europa.eu/services/disclaimer/html/index.en.html",
-        attribution: "FX data: European Central Bank reference rates via Frankfurter"
+        attribution: "FX data: European Central Bank reference rates via Frankfurter",
       },
       {
         id: "fx_vnd",
@@ -69,14 +69,15 @@ module Timeprice
         name: "World Bank — PA.NUS.FCRF (VND annual average, broadcast daily)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "VND FX: World Bank, PA.NUS.FCRF"
-      }
+        attribution: "VND FX: World Bank, PA.NUS.FCRF",
+      },
     ].freeze
 
     module_function
 
     # Returns an array of hashes with :id, :kind, :name, :license, :license_url,
     # :attribution, :coverage (string like "1990-01 to 2026-03 (monthly+annual)").
+    # @return [Array<Hash>]
     def list
       ATTRIBUTIONS.map { |s| s.merge(coverage: coverage_for(s)) }
     end
@@ -105,6 +106,7 @@ module Timeprice
       root = File.join(DataLoader.data_root, "fx", "usd")
       years = Dir[File.join(root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
       return "no data" if years.empty?
+
       case id
       when "fx_vnd"
         # VND broadcast-from-annual covers earlier years too.
@@ -113,14 +115,16 @@ module Timeprice
           d["rates"].any? { |_, v| v.key?("VND") }
         end
         return "no VND data" if with_vnd.empty?
+
         "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
       else
         # ECB pairs (EUR/GBP/JPY) start 1999
         ecb_years = years.select do |y|
           d = JSON.parse(File.read(File.join(root, "#{y}.json")))
-          d["rates"].any? { |_, v| (v.keys & %w[EUR GBP JPY]).any? }
+          d["rates"].any? { |_, v| v.keys.intersect?(%w[EUR GBP JPY]) }
         end
         return "no ECB data" if ecb_years.empty?
+
         "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
       end
     end

data/lib/timeprice/supported.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # Canonical lists of supported country and currency codes, plus the
+  # bidirectional currency↔country map used by `Compare` and CLI output.
+  #
+  # Everything that needs to know "which currency pairs with which CPI series"
+  # must read it from here — duplicating the map elsewhere has bitten us before
+  # when a new country was added in one place and forgotten in the other.
+  module Supported
+    COUNTRIES  = %w[US UK EU JP VN].freeze
+    CURRENCIES = %w[USD GBP EUR JPY VND].freeze
+
+    COUNTRY_TO_CURRENCY = {
+      "US" => "USD",
+      "UK" => "GBP",
+      "EU" => "EUR",
+      "JP" => "JPY",
+      "VN" => "VND",
+    }.freeze
+
+    CURRENCY_TO_COUNTRY = COUNTRY_TO_CURRENCY.invert.freeze
+
+    module_function
+
+    # @param country [String]
+    # @return [Boolean]
+    def country?(country)
+      COUNTRIES.include?(country.to_s.upcase)
+    end
+
+    # @param currency [String]
+    # @return [Boolean]
+    def currency?(currency)
+      CURRENCIES.include?(currency.to_s.upcase)
+    end
+
+    # @param currency [String] ISO 4217 code (e.g. "USD")
+    # @return [String, nil] country code, or nil if unsupported
+    def country_for_currency(currency)
+      CURRENCY_TO_COUNTRY[currency.to_s.upcase]
+    end
+
+    # @param country [String] country code (e.g. "US")
+    # @return [String, nil] currency code, or nil if unsupported
+    def currency_for_country(country)
+      COUNTRY_TO_CURRENCY[country.to_s.upcase]
+    end
+  end
+
+  # Back-compat aliases — keep the old top-level constants pointing at the
+  # canonical lists so existing requires of "errors" keep working.
+  SUPPORTED_COUNTRIES  = Supported::COUNTRIES
+  SUPPORTED_CURRENCIES = Supported::CURRENCIES
+end

data/lib/timeprice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Timeprice
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/timeprice.rb

@@ -1,24 +1,64 @@
 # frozen_string_literal: true
 
 require_relative "timeprice/version"
+require_relative "timeprice/supported"
 require_relative "timeprice/errors"
+require_relative "timeprice/point"
 require_relative "timeprice/data_loader"
 require_relative "timeprice/inflation"
 require_relative "timeprice/exchange"
 require_relative "timeprice/compare"
 require_relative "timeprice/sources"
 
+# Offline historical inflation & FX for Ruby.
+#
+# Top-level module functions wrap the three core operations: inflation
+# adjustment, currency exchange, and a combined "compare" that does both
+# in the right order. Each returns an immutable `Data.define` value object.
+#
+# @example Inflation
+#   Timeprice.inflation(amount: 100, from: "1990-01", to: "2024-01", country: "US")
+# @example FX
+#   Timeprice.exchange(amount: 100, from: "USD", to: "JPY", date: "2010-06-15")
+# @example Compare
+#   Timeprice.compare(amount: 100, from: ["USD", "2010"], to: ["VND", "2024"])
 module Timeprice
   module_function
 
+  # Inflation-adjust an amount between two dates using a country's CPI.
+  #
+  # @param amount  [Numeric] the original amount
+  # @param from    [String]  source date as "YYYY" or "YYYY-MM"
+  # @param to      [String]  target date as "YYYY" or "YYYY-MM"
+  # @param country [String]  country code from {Supported::COUNTRIES}
+  # @return [InflationResult]
+  # @raise [UnsupportedCountry] if `country` is not supported
+  # @raise [DataNotFound]       if no CPI point covers `from` or `to`
   def inflation(amount:, from:, to:, country:)
     Inflation.adjust(amount: amount, from: from, to: to, country: country)
   end
 
+  # Convert an amount between currencies on a specific date.
+  #
+  # @param amount [Numeric] the original amount
+  # @param from   [String]  source currency (ISO 4217)
+  # @param to     [String]  destination currency (ISO 4217)
+  # @param date   [String]  date as "YYYY-MM-DD"
+  # @return [ExchangeResult]
+  # @raise [UnsupportedCurrency] if either currency is not supported
+  # @raise [DataNotFound]        if no FX point exists within the fallback window
   def exchange(amount:, from:, to:, date:)
     Exchange.convert(amount: amount, from: from, to: to, date: date)
   end
 
+  # Compare an amount across two (currency, date) points: convert at the
+  # source date, then inflate in the destination currency. See README.md
+  # "Compare semantics" for why this order is correct.
+  #
+  # @param amount [Numeric]
+  # @param from   [Point, Array(String, String)] source point
+  # @param to     [Point, Array(String, String)] destination point
+  # @return [CompareResult]
   def compare(amount:, from:, to:)
     Compare.run(amount: amount, from: from, to: to)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Patrick
@@ -51,6 +51,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 description: Offline historical inflation & FX for Ruby - bundled data, no API keys,
   monthly auto-refresh.
 email:
@@ -120,7 +162,9 @@ files:
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
 - lib/timeprice/inflation.rb
+- lib/timeprice/point.rb
 - lib/timeprice/sources.rb
+- lib/timeprice/supported.rb
 - lib/timeprice/version.rb
 homepage: https://github.com/patrick204nqh/timeprice
 licenses:
@@ -130,6 +174,7 @@ metadata:
   bug_tracker_uri: https://github.com/patrick204nqh/timeprice/issues
   changelog_uri: https://github.com/patrick204nqh/timeprice/blob/main/CHANGELOG.md
   github_repo: patrick204nqh/timeprice
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib