timeprice 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ebaf1340f0abefa6b4dcae31f7d2f2d22021155d24ebc258f15b0495f7a480
-  data.tar.gz: 6068762094c6008c72f4dd7becb10e1e8cb0d0c17b668234e8e0dff84c494cc2
+  metadata.gz: 160a9501bc1004df45cd71202f3ae07711068adade2118cfe4605a2e92d92f6f
+  data.tar.gz: 68ea05103245f2bb1fb02d701fd5db6e1bb814a2b47d20f6eb9011d94a57b269
 SHA512:
-  metadata.gz: fa08a556599384d4ae292064b2342bfdc6976eac3fea784afb7426d623fdd0c8ee43001135bd2f7c3a065e735db8dd6d347459144e44ee702f30505ee23c3c1f
-  data.tar.gz: 9fd49be55c8790b4a1adfd9350fdd2e6eed82cdcbf8e41c2dd3b1e1514e5b81f9ffa71dc0a9b530738ac2f2d6fa22e969c240bd81dac043e4a4b8e23b21b6924
+  metadata.gz: fdddfd9cbcf4cefad6ee73134eb8ef3e5ad5b863aa8d5a78fa789b8890cefec0690cf3c1022f1b596c2bdeaf6f9a8f1122d8ff6ef9adfb7dd393e0aa9346afb6
+  data.tar.gz: 4342d02e30f4058f6e7a98eedab2fd0fa54b14031f061bf4d17b093d02f6a1e5cd16ea1f994e7d868cc893fe29119bdae1a398724665f14502c9b135ee1396b0

data/CHANGELOG.md

@@ -5,6 +5,20 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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

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

@@ -203,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"
 
@@ -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)
@@ -84,6 +79,19 @@ module Timeprice
       )
     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,26 +4,41 @@ 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
@@ -41,6 +56,10 @@ module Timeprice
         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

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,7 +20,14 @@ 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

data/lib/timeprice/inflation.rb

@@ -16,12 +16,21 @@ 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)
@@ -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

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

@@ -77,6 +77,7 @@ module Timeprice
 
     # 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

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.2"
+  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.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Patrick
@@ -162,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: