timeprice 0.6.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,14 +161,29 @@
       "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": 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",
+  "generated_at": "2026-05-12",
   "schema_version": 4
 }

data/lib/timeprice/cli.rb

@@ -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

@@ -32,7 +32,7 @@ module Timeprice
       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 raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, or YYYY-Qn)"
+      else fail ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, or YYYY-Qn)"
       end
     end
 
@@ -48,7 +48,7 @@ module Timeprice
       end
 
       year_key = month_key[0, 4]
-      raise DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
+      fail DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
 
       CpiPoint.new(value: @annual[year_key], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
@@ -71,7 +71,7 @@ module Timeprice
       end
 
       year = quarter_key[0, 4]
-      raise DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
+      fail DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
 
       CpiPoint.new(value: @annual[year], granularity: Granularity::QUARTERLY_FROM_ANNUAL_FALLBACK)
     end
@@ -90,7 +90,7 @@ module Timeprice
       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?
 
-      raise DataNotFound, missing_message(year)
+      fail DataNotFound, missing_message(year)
     end
 
     def average(series, divisor, granularity)

data/lib/timeprice/data_loader.rb

@@ -2,18 +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 = 4
-
-    # Files written by older toolchains remain readable: v3 is monthly+annual
-    # only; v4 adds an optional `series.quarterly` block.
-    SUPPORTED_SCHEMA_VERSIONS = [3, 4].freeze
-
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
@@ -46,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)
@@ -64,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)
@@ -84,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
@@ -116,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 SUPPORTED_SCHEMA_VERSIONS.include?(version)
-
-        data
+        Schema.load_cpi(JSON.parse(File.read(path)), path: path)
       end
     end
   end

data/lib/timeprice/date.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Timeprice
+  # Raised when a user-supplied date string can't be parsed into a
+  # {Timeprice::Date} value.
+  class InvalidDate < Error; end
+
+  # Immutable value object representing "a date at some granularity": a
+  # year, a year+month, a year+quarter, or a full calendar day. Used as
+  # the canonical input shape for the public API (`Timeprice.inflation`,
+  # `Timeprice.exchange`, `Timeprice.compare`) — strings are accepted for
+  # convenience and coerced via {.coerce} at the boundary.
+  # rubocop:disable Lint/ConstantDefinitionInBlock
+  Date = Data.define(:year, :month, :quarter, :day) do
+    ANNUAL_RE    = /\A(\d{4})\z/
+    MONTHLY_RE   = /\A(\d{4})-(\d{2})\z/
+    QUARTERLY_RE = /\A(\d{4})-Q([1-4])\z/i
+    DAILY_RE     = /\A(\d{4})-(\d{2})-(\d{2})\z/
+
+    def self.parse(str)
+      case str.to_s
+      when DAILY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: ::Regexp.last_match(2).to_i,
+            quarter: nil, day: ::Regexp.last_match(3).to_i)
+      when QUARTERLY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: nil,
+            quarter: ::Regexp.last_match(2).to_i, day: nil)
+      when MONTHLY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: ::Regexp.last_match(2).to_i,
+            quarter: nil, day: nil)
+      when ANNUAL_RE
+        new(year: ::Regexp.last_match(1).to_i, month: nil, quarter: nil, day: nil)
+      else
+        fail InvalidDate, "Cannot parse #{str.inspect} as a Timeprice::Date"
+      end
+    end
+
+    def self.coerce(input)
+      input.is_a?(self) ? input : parse(input)
+    end
+
+    def granularity
+      return :daily     if day
+      return :monthly   if month
+      return :quarterly if quarter
+
+      :annual
+    end
+
+    def to_s
+      case granularity
+      when :daily     then format("%04d-%02d-%02d", year, month, day)
+      when :monthly   then format("%04d-%02d", year, month)
+      when :quarterly then format("%04d-Q%d", year, quarter)
+      else format("%04d", year)
+      end
+    end
+  end
+  # rubocop:enable Lint/ConstantDefinitionInBlock
+end