timeprice 0.5.0 → 0.7.0

data/data/fx/usd/_annual.json

@@ -25,6 +25,7 @@
       "VND": 11202.19
     },
     "1993": {
+      "RUB": 0.9917,
       "VND": 10640.96
     },
     "1994": {
@@ -34,90 +35,119 @@
       "VND": 11038.25
     },
     "1996": {
+      "RUB": 5.1208,
       "VND": 11032.58
     },
     "1997": {
+      "RUB": 5.7848,
       "VND": 11683.33
     },
     "1998": {
+      "RUB": 9.7051,
       "VND": 13268.0
     },
     "1999": {
+      "RUB": 24.6199,
       "VND": 13943.17
     },
     "2000": {
+      "RUB": 28.1292,
       "VND": 14167.75
     },
     "2001": {
+      "RUB": 29.1685,
       "VND": 14725.17
     },
     "2002": {
+      "RUB": 31.3485,
       "VND": 15279.5
     },
     "2003": {
+      "RUB": 30.692,
       "VND": 15509.58
     },
     "2004": {
+      "RUB": 28.8137,
       "VND": 15746.0
     },
     "2005": {
+      "RUB": 28.2844,
       "VND": 15858.92
     },
     "2006": {
+      "RUB": 27.191,
       "VND": 15994.25
     },
     "2007": {
+      "RUB": 25.5808,
       "VND": 16105.13
     },
     "2008": {
+      "RUB": 24.8529,
       "VND": 16302.25
     },
     "2009": {
+      "RUB": 31.7404,
       "VND": 17065.08
     },
     "2010": {
+      "RUB": 30.3679,
       "VND": 18612.92
     },
     "2011": {
+      "RUB": 29.3823,
       "VND": 20509.75
     },
     "2012": {
+      "RUB": 30.8398,
       "VND": 20828.0
     },
     "2013": {
+      "RUB": 31.8371,
       "VND": 20933.42
     },
     "2014": {
+      "RUB": 38.3782,
       "VND": 21148.0
     },
     "2015": {
+      "RUB": 60.9377,
       "VND": 21697.57
     },
     "2016": {
+      "RUB": 67.0559,
       "VND": 21935.0
     },
     "2017": {
+      "RUB": 58.3428,
       "VND": 22370.09
     },
     "2018": {
+      "RUB": 62.6681,
       "VND": 22602.05
     },
     "2019": {
+      "RUB": 64.7377,
       "VND": 23050.24
     },
     "2020": {
+      "RUB": 72.1049,
       "VND": 23208.37
     },
     "2021": {
+      "RUB": 73.6544,
       "VND": 23159.78
     },
     "2022": {
+      "RUB": 68.4849,
       "VND": 23271.21
     },
     "2023": {
+      "RUB": 85.162,
       "VND": 23787.32
     },
     "2024": {
+      "RUB": 92.5524,
       "VND": 24164.89
     }
   },
@@ -131,15 +161,30 @@
       "provider": "world_bank",
       "series": "annual",
       "to": "2024"
+    },
+    {
+      "currencies": [
+        "RUB"
+      ],
+      "from": "1993",
+      "provider": "imf",
+      "series": "annual",
+      "to": "2024"
     }
   ],
   "providers": [
     {
-      "fetched_at": "2026-05-11",
+      "fetched_at": "2026-05-12",
       "id": "world_bank",
       "label": "World Bank PA.NUS.FCRF",
       "status": "ok"
+    },
+    {
+      "fetched_at": "2026-05-12",
+      "id": "imf",
+      "label": "IMF ER dataflow XDC_USD/PA_RT (period-average, annual mean)",
+      "status": "ok"
     }
   ],
-  "schema_version": 3
+  "schema_version": 4
 }

data/data/manifest.json

@@ -1,5 +1,62 @@
 {
   "countries": [
+    {
+      "code": "AU",
+      "cpi_file": "cpi/au.json",
+      "currency": "AUD",
+      "granularities": [
+        "quarterly",
+        "annual"
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1960",
+          "max": "2024"
+        },
+        "quarterly": {
+          "min": "1948-Q3",
+          "max": "2026-Q1"
+        }
+      }
+    },
+    {
+      "code": "CA",
+      "cpi_file": "cpi/ca.json",
+      "currency": "CAD",
+      "granularities": [
+        "monthly",
+        "annual"
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1914",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1914-01",
+          "max": "2026-03"
+        }
+      }
+    },
+    {
+      "code": "CN",
+      "cpi_file": "cpi/cn.json",
+      "currency": "CNY",
+      "granularities": [
+        "monthly",
+        "annual"
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1986",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1993-01",
+          "max": "2026-03"
+        }
+      }
+    },
     {
       "code": "EU",
       "cpi_file": "cpi/eu.json",
@@ -7,7 +64,17 @@
       "granularities": [
         "monthly",
         "annual"
-      ]
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1996",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1996-01",
+          "max": "2025-12"
+        }
+      }
     },
     {
       "code": "JP",
@@ -15,7 +82,51 @@
       "currency": "JPY",
       "granularities": [
         "annual"
-      ]
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1960",
+          "max": "2024"
+        }
+      }
+    },
+    {
+      "code": "KR",
+      "cpi_file": "cpi/kr.json",
+      "currency": "KRW",
+      "granularities": [
+        "monthly",
+        "annual"
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1960",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1990-01",
+          "max": "2026-03"
+        }
+      }
+    },
+    {
+      "code": "RU",
+      "cpi_file": "cpi/ru.json",
+      "currency": "RUB",
+      "granularities": [
+        "monthly",
+        "annual"
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1992",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1992-01",
+          "max": "2026-03"
+        }
+      }
     },
     {
       "code": "UK",
@@ -24,7 +135,17 @@
       "granularities": [
         "monthly",
         "annual"
-      ]
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1988",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "1988-01",
+          "max": "2026-03"
+        }
+      }
     },
     {
       "code": "US",
@@ -33,7 +154,17 @@
       "granularities": [
         "monthly",
         "annual"
-      ]
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1990",
+          "max": "2024"
+        },
+        "monthly": {
+          "min": "1990-01",
+          "max": "2026-03"
+        }
+      }
     },
     {
       "code": "VN",
@@ -42,16 +173,31 @@
       "granularities": [
         "monthly",
         "annual"
-      ]
+      ],
+      "cpi_ranges": {
+        "annual": {
+          "min": "1995",
+          "max": "2025"
+        },
+        "monthly": {
+          "min": "2001-12",
+          "max": "2026-03"
+        }
+      }
     }
   ],
   "fx": {
     "annual_file": "fx/usd/_annual.json",
     "base": "USD",
     "currencies": [
+      "AUD",
+      "CAD",
+      "CNY",
       "EUR",
       "GBP",
       "JPY",
+      "KRW",
+      "RUB",
       "VND"
     ],
     "daily_years": [
@@ -83,8 +229,10 @@
       2024,
       2025,
       2026
-    ]
+    ],
+    "daily_min": "1999-01-04",
+    "daily_max": "2026-05-11"
   },
-  "generated_at": "2026-05-11",
-  "schema_version": 3
+  "generated_at": "2026-05-12",
+  "schema_version": 4
 }

data/lib/timeprice/cli.rb

@@ -76,9 +76,9 @@ module Timeprice
     end
 
     desc "inflation AMOUNT", "Inflation-adjust an amount between two dates"
-    method_option :from,    type: :string, required: true, desc: "Source date (YYYY or YYYY-MM)"
-    method_option :to,      type: :string, required: true, desc: "Target date (YYYY or YYYY-MM)"
-    method_option :country, type: :string, required: true, desc: "Country code (US, UK, EU, JP, VN)"
+    method_option :from,    type: :string, required: true, desc: "Source date (YYYY, YYYY-MM, or YYYY-Qn)"
+    method_option :to,      type: :string, required: true, desc: "Target date (YYYY, YYYY-MM, or YYYY-Qn)"
+    method_option :country, type: :string, required: true, desc: "Country code (US, UK, EU, JP, VN, AU, CA, KR, CN, RU)"
     def inflation(amount)
       with_error_handling do
         result = Timeprice.inflation(
@@ -160,12 +160,12 @@ module Timeprice
       end
 
       def parse_compare_token(token, label:)
-        raise ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
+        fail ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
 
         parts = token.strip.split(/\s+/)
         unless parts.size == 2
-          raise ArgumentError,
-                "#{label} must be \"YEAR CURRENCY\" or \"CURRENCY YEAR\", got #{token.inspect}"
+          fail ArgumentError,
+               "#{label} must be \"YEAR CURRENCY\" or \"CURRENCY YEAR\", got #{token.inspect}"
         end
 
         Point.coerce(parts)

data/lib/timeprice/compare.rb

@@ -28,6 +28,11 @@ module Timeprice
   #
   # If a future refactor flips the order, the regression test in
   # spec/timeprice/compare_spec.rb will fail.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.compare}. Direct
+  # references will move to `Timeprice::Internal::Compare` in a future
+  # release.
   module Compare
     module_function
 
@@ -52,7 +57,17 @@ module Timeprice
       converted = fx_result.amount
 
       # Step 2: inflate that destination-currency amount from source date to
-      # destination date using destination-country CPI.
+      # destination date using destination-country CPI. When both points
+      # share a date there's no time-elapsed inflation to apply — short-
+      # circuit with a ratio of 1.0 so daily-grain FX dates (which CPI's
+      # monthly-max resolution can't accept) still resolve cleanly.
+      if from_point.date == to_point.date
+        return fx_only_result(
+          amount: amount, from_point: from_point, to_point: to_point,
+          to_country: to_country, fx_result: fx_result
+        )
+      end
+
       infl = Inflation.adjust(
         amount: converted,
         from: from_point.date.to_s,
@@ -75,14 +90,32 @@ module Timeprice
       )
     end
 
+    # Same-date branch: no time-elapsed inflation, so the FX leg alone is
+    # the answer. Builds a CompareResult with cpi_ratio=1.0.
+    def fx_only_result(amount:, from_point:, to_point:, to_country:, fx_result:)
+      CompareResult.new(
+        amount: fx_result.amount,
+        original_amount: amount.to_f,
+        from_currency: from_point.currency,
+        from_date: from_point.date.to_s,
+        to_currency: to_point.currency,
+        to_date: to_point.date.to_s,
+        country: to_country,
+        fx_rate: fx_result.rate,
+        cpi_ratio: 1.0,
+        converted_amount: fx_result.amount,
+        granularity: fx_result.granularity
+      )
+    end
+
     # Coerce both points and resolve to_country.
     def resolve_points(from, to)
       from_point = Point.coerce(from)
       to_point   = Point.coerce(to)
-      raise UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
+      fail UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
 
       to_country = Supported.country_for_currency(to_point.currency)
-      raise UnsupportedCurrency, to_point.currency unless to_country
+      fail UnsupportedCurrency, to_point.currency unless to_country
 
       [from_point, to_point, to_country]
     end

data/lib/timeprice/cpi_lookup.rb

@@ -8,54 +8,100 @@ module Timeprice
   # resolved. See {Granularity} for the full set of possible tags.
   CpiPoint = Data.define(:value, :granularity)
 
-  # Resolves CPI keys ("YYYY" or "YYYY-MM") to a CpiPoint against a single
-  # country's parsed CPI data hash. Knowing the JSON shape ("monthly" /
-  # "annual" string keys) is isolated here — Inflation just asks for points.
+  # Resolves CPI keys ("YYYY", "YYYY-MM", or "YYYY-Qn") to a CpiPoint against
+  # a single country's parsed CPI data hash. Knowing the JSON shape ("monthly"
+  # / "quarterly" / "annual" string keys) is isolated here — Inflation just
+  # asks for points.
   class CpiLookup
+    QUARTER_RE = /\A(\d{4})-Q([1-4])\z/
+
     def initialize(data)
       @data = data
-      @monthly = data.dig("series", "monthly") || {}
-      @annual  = data.dig("series", "annual")  || {}
+      @monthly   = data.dig("series", "monthly")   || {}
+      @quarterly = data.dig("series", "quarterly") || {}
+      @annual    = data.dig("series", "annual")    || {}
     end
 
-    # @param key [String] "YYYY" or "YYYY-MM"
+    # @param key [String] "YYYY", "YYYY-MM", or "YYYY-Qn"
     # @return [CpiPoint]
     # @raise [DataNotFound] if no CPI value covers `key`
     # @raise [ArgumentError] on malformed `key`
     def at(key)
       key = key.to_s
       case key
-      when /\A\d{4}-\d{2}\z/ then monthly_or_annual_fallback(key)
-      when /\A\d{4}\z/       then annual_or_monthly_average(key)
-      else raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
+      when QUARTER_RE        then quarterly_or_fallbacks(key)
+      when /\A\d{4}-\d{2}\z/ then monthly_or_fallbacks(key)
+      when /\A\d{4}\z/       then annual_or_derived(key)
+      else fail ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, or YYYY-Qn)"
       end
     end
 
     private
 
-    def monthly_or_annual_fallback(month_key)
+    def monthly_or_fallbacks(month_key)
       return CpiPoint.new(value: @monthly[month_key], granularity: Granularity::MONTHLY) if @monthly.key?(month_key)
 
-      year = month_key[0, 4]
-      raise DataNotFound, missing_message(month_key) unless @annual.key?(year)
+      year, month = month_key.split("-").map(&:to_i)
+      qkey = format("%04d-Q%d", year, ((month - 1) / 3) + 1)
+      if @quarterly.key?(qkey)
+        return CpiPoint.new(value: @quarterly[qkey], granularity: Granularity::MONTHLY_FROM_QUARTERLY_FALLBACK)
+      end
+
+      year_key = month_key[0, 4]
+      fail DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
 
-      CpiPoint.new(value: @annual[year], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
+      CpiPoint.new(value: @annual[year_key], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
 
-    def annual_or_monthly_average(year)
+    def quarterly_or_fallbacks(quarter_key)
+      if @quarterly.key?(quarter_key)
+        return CpiPoint.new(value: @quarterly[quarter_key],
+                            granularity: Granularity::QUARTERLY)
+      end
+
+      year_int, q = quarter_key.match(QUARTER_RE).captures.map(&:to_i)
+      first_month = ((q - 1) * 3) + 1
+      last_month  = q * 3
+      months = (first_month..last_month).map { |m| format("%04d-%02d", year_int, m) }
+                                        .map { |k| @monthly[k] }
+                                        .compact
+      if months.size == 3
+        return CpiPoint.new(value: months.sum.to_f / 3,
+                            granularity: Granularity::QUARTERLY_FROM_MONTHLY_AVG)
+      end
+
+      year = quarter_key[0, 4]
+      fail DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
+
+      CpiPoint.new(value: @annual[year], granularity: Granularity::QUARTERLY_FROM_ANNUAL_FALLBACK)
+    end
+
+    def annual_or_derived(year)
       return CpiPoint.new(value: @annual[year], granularity: Granularity::ANNUAL) if @annual.key?(year)
 
-      months = @monthly.select { |k, _| k.start_with?("#{year}-") }
-      raise DataNotFound, missing_message(year) if months.empty?
+      months   = @monthly.select { |k, _| k.start_with?("#{year}-") }
+      quarters = @quarterly.select { |k, _| k.start_with?("#{year}-Q") }
+
+      # Prefer complete-period averages over partials, and within each, prefer
+      # monthly resolution. Partial tags distinguish biased estimates (e.g.
+      # only Jan-Feb populated) from a true full-year mean.
+      return average(months, 12, Granularity::ANNUAL_FROM_MONTHLY_AVG) if months.size == 12
+      return average(quarters, 4, Granularity::ANNUAL_FROM_QUARTERLY_AVG) if quarters.size == 4
+      return average(months, months.size, Granularity::ANNUAL_FROM_PARTIAL_MONTHS) if months.any?
+      return average(quarters, quarters.size, Granularity::ANNUAL_FROM_PARTIAL_QUARTERS) if quarters.any?
+
+      fail DataNotFound, missing_message(year)
+    end
 
-      avg = months.values.sum.to_f / months.size
-      CpiPoint.new(value: avg, granularity: Granularity::ANNUAL_FROM_MONTHLY_AVG)
+    def average(series, divisor, granularity)
+      CpiPoint.new(value: series.values.sum.to_f / divisor, granularity: granularity)
     end
 
     def missing_message(key)
       country = @data["country"]
       ranges = []
       ranges << "monthly #{@monthly.keys.min}..#{@monthly.keys.max}" if @monthly.any?
+      ranges << "quarterly #{@quarterly.keys.min}..#{@quarterly.keys.max}" if @quarterly.any?
       ranges << "annual #{@annual.keys.min}..#{@annual.keys.max}" if @annual.any?
       hint = ranges.empty? ? "" : " (supported: #{ranges.join(", ")})"
       "No CPI data for #{key.inspect} in #{country}#{hint}"

data/lib/timeprice/data_loader.rb

@@ -2,14 +2,13 @@
 
 require "json"
 require_relative "errors"
+require_relative "schema"
 
 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 = 3
-
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
@@ -42,8 +41,8 @@ module Timeprice
         manifest_cache[data_root] ||= begin
           path = File.join(data_root, "manifest.json")
           unless File.exist?(path)
-            raise DataNotFound, "manifest.json missing (looked in #{path}). " \
-                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+            fail DataNotFound, "manifest.json missing (looked in #{path}). " \
+                               "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
           end
 
           parse_with_schema(path)
@@ -60,12 +59,12 @@ module Timeprice
         key = country.to_s.downcase
         code = country.to_s.upcase
         cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless Supported.country?(code)
+          fail UnsupportedCountry, code unless Supported.country?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
-            raise DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
-                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+            fail DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
+                               "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
           end
 
           parse_with_schema(path)
@@ -80,7 +79,7 @@ module Timeprice
         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)
+          fail DataNotFound, "No FX data for year #{key}" unless File.exist?(path)
 
           parse_with_schema(path)
         end
@@ -112,11 +111,7 @@ module Timeprice
       end
 
       def parse_with_schema(path)
-        data = JSON.parse(File.read(path))
-        version = data["schema_version"]
-        raise UnsupportedSchemaVersion.new(version, path) unless version == SUPPORTED_SCHEMA_VERSION
-
-        data
+        Schema.load_cpi(JSON.parse(File.read(path)), path: path)
       end
     end
   end