timeprice 0.1.0

data/lib/timeprice/compare.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "inflation"
+require_relative "exchange"
+
+module Timeprice
+  CompareResult = Data.define(
+    :amount, :original_amount,
+    :from_currency, :from_date,
+    :to_currency, :to_date,
+    :country, :fx_rate, :cpi_ratio,
+    :converted_amount, :granularity
+  )
+
+  # 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.
+  #
+  # This preserves purchasing-power equivalence in the destination economy.
+  # The naive alternative (inflate in source currency first, then convert at
+  # destination date) double-counts source-country inflation because nominal
+  # FX rates already absorb relative inflation between the two currencies.
+  #
+  # 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
+
+    module_function
+
+    # amount: Numeric
+    # from:   [currency, date_or_year] e.g. ["USD", "2010"] or ["USD", "2010-06"]
+    # to:     [currency, date_or_year]
+    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)
+
+      # Step 1: convert at source date into destination currency.
+      fx_date = normalize_fx_date(from_date)
+      fx_result = Exchange.convert(
+        amount: amount,
+        from: from_currency,
+        to: to_currency,
+        date: fx_date
+      )
+      converted = fx_result.amount
+
+      # Step 2: inflate that destination-currency amount from source date to
+      # destination date using destination-country CPI.
+      infl = Inflation.adjust(
+        amount: converted,
+        from: from_date.to_s,
+        to: to_date.to_s,
+        country: to_country
+      )
+
+      CompareResult.new(
+        amount: infl.amount,
+        original_amount: amount.to_f,
+        from_currency: from_currency,
+        from_date: from_date.to_s,
+        to_currency: to_currency,
+        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,
+        converted_amount: converted,
+        granularity: infl.granularity
+      )
+    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)
+      s = date.to_s
+      case s
+      when /\A\d{4}\z/ then "#{s}-06-30"
+      when /\A\d{4}-\d{2}\z/ then "#{s}-15"
+      when /\A\d{4}-\d{2}-\d{2}\z/ then s
+      else raise ArgumentError, "Invalid date for compare: #{date.inspect}"
+      end
+    end
+  end
+end

data/lib/timeprice/data_loader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+
+module Timeprice
+  module DataLoader
+    SUPPORTED_SCHEMA_VERSION = 1
+
+    DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
+
+    class << self
+      def data_root
+        ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
+      end
+
+      def data_root=(path)
+        @data_root = path
+        clear_cache!
+      end
+
+      def clear_cache!
+        @cpi_cache = {}
+        @fx_cache = {}
+      end
+
+      def load_cpi(country)
+        @cpi_cache ||= {}
+        key = country.to_s.downcase
+        @cpi_cache[[data_root, key]] ||= begin
+          path = File.join(data_root, "cpi", "#{key}.json")
+          raise UnsupportedCountry, country.to_s.upcase unless File.exist?(path)
+          parse_with_schema(path)
+        end
+      end
+
+      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
+
+      private
+
+      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
+        data
+      end
+    end
+  end
+end

data/lib/timeprice/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Timeprice
+  class Error < StandardError; end
+
+  class UnsupportedCountry < Error
+    attr_reader :country
+
+    def initialize(country)
+      @country = country
+      super("Unsupported country: #{country.inspect}")
+    end
+  end
+
+  class UnsupportedCurrency < Error
+    attr_reader :currency
+
+    def initialize(currency)
+      @currency = currency
+      super("Unsupported currency: #{currency.inspect}")
+    end
+  end
+
+  class DateOutOfRange < Error
+    attr_reader :date, :range
+
+    def initialize(date, range)
+      @date = date
+      @range = range
+      super("Date #{date.inspect} out of supported range #{range.inspect}")
+    end
+  end
+
+  class DataNotFound < Error
+    def initialize(message = "Data not found")
+      super
+    end
+  end
+
+  class UnsupportedSchemaVersion < Error
+    attr_reader :version, :path
+
+    def initialize(version, path)
+      @version = version
+      @path = path
+      super("Unsupported schema_version #{version.inspect} in #{path}")
+    end
+  end
+end

data/lib/timeprice/exchange.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "errors"
+require_relative "data_loader"
+
+module Timeprice
+  ExchangeResult = Data.define(
+    :amount, :original_amount, :from, :to, :date, :effective_date, :rate
+  )
+
+  module Exchange
+    BASE = "USD"
+    MAX_FALLBACK_DAYS = 7
+
+    module_function
+
+    # Convert `amount` from currency `from` to currency `to` on `date`.
+    # date: "YYYY-MM-DD".
+    def convert(amount:, from:, to:, date:)
+      from = from.to_s.upcase
+      to   = to.to_s.upcase
+      d = parse_date(date)
+
+      rate, eff_date = resolve_rate(from, to, d)
+      ExchangeResult.new(
+        amount: amount.to_f * rate,
+        original_amount: amount.to_f,
+        from: from,
+        to: to,
+        date: d.to_s,
+        effective_date: eff_date.to_s,
+        rate: rate
+      )
+    end
+
+    # Returns [rate (Float), effective_date (Date)].
+    # Handles:
+    #   - identity (from == to)
+    #   - direct lookup of USD-base rate
+    #   - inverse (foreign → USD)
+    #   - triangulation through USD (both legs must resolve to SAME effective date)
+    def resolve_rate(from, to, d)
+      return [1.0, d] if from == to
+
+      if from == BASE
+        rate, eff = lookup_usd_base(to, d)
+        [rate, eff]
+      elsif to == BASE
+        rate, eff = lookup_usd_base(from, d)
+        [1.0 / rate, eff]
+      else
+        # Triangulation: from → USD → to, both legs at the same effective date.
+        usd_to_from, eff_a = lookup_usd_base(from, d)
+        usd_to_to,   eff_b = lookup_usd_base(to,   d)
+        if eff_a != eff_b
+          raise DataNotFound,
+                "FX triangulation date mismatch for #{from}->#{to} on #{d}: " \
+                "USD->#{from} resolved #{eff_a}, USD->#{to} resolved #{eff_b}"
+        end
+        [usd_to_to / usd_to_from, eff_a]
+      end
+    end
+
+    # Walk back up to MAX_FALLBACK_DAYS to find a rate.
+    # Returns [rate, effective_date].
+    def lookup_usd_base(currency, d)
+      (0..MAX_FALLBACK_DAYS).each do |offset|
+        candidate = d - offset
+        year_data =
+          begin
+            DataLoader.load_fx_year(candidate.year)
+          rescue DataNotFound
+            next
+          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}"
+    end
+
+    def parse_date(date)
+      case date
+      when Date then date
+      when String
+        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)
+      else
+        raise ArgumentError, "Invalid date: #{date.inspect}"
+      end
+    end
+  end
+end

data/lib/timeprice/inflation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "data_loader"
+
+module Timeprice
+  # Value object returned by Inflation.adjust.
+  #
+  # granularity is one of:
+  #   :monthly                  — both ends resolved on monthly data
+  #   :annual                   — at least one end resolved on annual data
+  #   :annual_from_monthly_avg  — at least one end was an annual request resolved
+  #                               by averaging 12 months of monthly data
+  InflationResult = Data.define(
+    :amount, :original_amount, :from, :to, :country,
+    :from_index, :to_index, :granularity
+  )
+
+  module Inflation
+    module_function
+
+    # Adjust `amount` from date `from` to date `to` using country CPI.
+    #
+    # Dates accept "YYYY" or "YYYY-MM".
+    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
+      InflationResult.new(
+        amount: amount.to_f * ratio,
+        original_amount: amount.to_f,
+        from: from,
+        to: to,
+        country: country.to_s.upcase,
+        from_index: from_index,
+        to_index: to_index,
+        granularity: merge_granularity(from_gran, to_gran)
+      )
+    end
+
+    # Inflation rate as decimal (e.g. 0.42 = 42%).
+    def rate(from:, to:, country:)
+      result = adjust(amount: 1.0, from: from, to: to, country: country)
+      result.amount - 1.0
+    end
+
+    # Returns [index_value, granularity_symbol]
+    def lookup_index(data, key)
+      key = key.to_s
+      monthly = data["monthly"] || {}
+      annual  = data["annual"]  || {}
+
+      case key
+      when /\A\d{4}-\d{2}\z/
+        if monthly.key?(key)
+          [monthly[key], :monthly]
+        else
+          year = key[0, 4]
+          if annual.key?(year)
+            [annual[year], :annual]
+          else
+            raise DataNotFound, "No CPI data for #{key.inspect} in #{data["country"]}"
+          end
+        end
+      when /\A\d{4}\z/
+        if annual.key?(key)
+          [annual[key], :annual]
+        else
+          months = monthly.select { |k, _| k.start_with?("#{key}-") }
+          raise DataNotFound, "No CPI data for #{key.inspect} in #{data["country"]}" if months.empty?
+          avg = months.values.sum.to_f / months.size
+          [avg, :annual_from_monthly_avg]
+        end
+      else
+        raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
+      end
+    end
+
+    # If either end fell back to annual_from_monthly_avg, propagate that label;
+    # else if either is annual, propagate :annual; else :monthly.
+    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
+end

data/lib/timeprice/sources.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "data_loader"
+
+module Timeprice
+  # Enumerate bundled data sources with license/attribution and the actual
+  # coverage range derived from data/ at runtime.
+  module Sources
+    # Static license & attribution metadata. Coverage is computed dynamically.
+    ATTRIBUTIONS = [
+      {
+        id: "us_cpi",
+        kind: "cpi",
+        country: "US",
+        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"
+      },
+      {
+        id: "uk_cpi",
+        kind: "cpi",
+        country: "UK",
+        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"
+      },
+      {
+        id: "eu_hicp",
+        kind: "cpi",
+        country: "EU",
+        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"
+      },
+      {
+        id: "jp_cpi",
+        kind: "cpi",
+        country: "JP",
+        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"
+      },
+      {
+        id: "vn_cpi",
+        kind: "cpi",
+        country: "VN",
+        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"
+      },
+      {
+        id: "fx_ecb",
+        kind: "fx",
+        country: nil,
+        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"
+      },
+      {
+        id: "fx_vnd",
+        kind: "fx",
+        country: "VN",
+        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"
+      }
+    ].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)").
+    def list
+      ATTRIBUTIONS.map { |s| s.merge(coverage: coverage_for(s)) }
+    end
+
+    def coverage_for(src)
+      case src[:kind]
+      when "cpi" then cpi_coverage(src[:country])
+      when "fx"  then fx_coverage(src[:id])
+      else "n/a"
+      end
+    rescue StandardError => e
+      "(coverage unavailable: #{e.message})"
+    end
+
+    def cpi_coverage(country)
+      data = DataLoader.load_cpi(country)
+      monthly = (data["monthly"] || {}).keys.sort
+      annual  = (data["annual"]  || {}).keys.sort
+      parts = []
+      parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
+      parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
+      parts.join(", ")
+    end
+
+    def fx_coverage(id)
+      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.
+        with_vnd = years.select do |y|
+          d = JSON.parse(File.read(File.join(root, "#{y}.json")))
+          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? }
+        end
+        return "no ECB data" if ecb_years.empty?
+        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
+      end
+    end
+  end
+end

data/lib/timeprice/version.rb

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

data/lib/timeprice.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "timeprice/version"
+require_relative "timeprice/errors"
+require_relative "timeprice/data_loader"
+require_relative "timeprice/inflation"
+require_relative "timeprice/exchange"
+require_relative "timeprice/compare"
+require_relative "timeprice/sources"
+
+module Timeprice
+  module_function
+
+  def inflation(amount:, from:, to:, country:)
+    Inflation.adjust(amount: amount, from: from, to: to, country: country)
+  end
+
+  def exchange(amount:, from:, to:, date:)
+    Exchange.convert(amount: amount, from: from, to: to, date: date)
+  end
+
+  def compare(amount:, from:, to:)
+    Compare.run(amount: amount, from: from, to: to)
+  end
+end