timeprice 0.3.0 → 0.5.0

data/data/fx/usd/2025.json

@@ -1,5 +1,26 @@
 {
   "base": "USD",
+  "provenance": [
+    {
+      "currencies": [
+        "EUR",
+        "GBP",
+        "JPY"
+      ],
+      "from": "2025-01-02",
+      "provider": "frankfurter",
+      "series": "daily",
+      "to": "2025-12-31"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "frankfurter",
+      "label": "Frankfurter (ECB) daily reference rates",
+      "status": "ok"
+    }
+  ],
   "rates": {
     "2025-01-02": {
       "EUR": 0.9689,
@@ -1277,8 +1298,6 @@
       "JPY": 156.67
     }
   },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
+  "schema_version": 3,
   "year": 2025
 }

data/data/fx/usd/2026.json

@@ -1,5 +1,26 @@
 {
   "base": "USD",
+  "provenance": [
+    {
+      "currencies": [
+        "EUR",
+        "GBP",
+        "JPY"
+      ],
+      "from": "2026-01-02",
+      "provider": "frankfurter",
+      "series": "daily",
+      "to": "2026-05-08"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "frankfurter",
+      "label": "Frankfurter (ECB) daily reference rates",
+      "status": "ok"
+    }
+  ],
   "rates": {
     "2026-01-02": {
       "EUR": 0.85317,
@@ -442,8 +463,6 @@
       "JPY": 156.76
     }
   },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
+  "schema_version": 3,
   "year": 2026
 }

data/data/fx/usd/_annual.json

@@ -0,0 +1,145 @@
+{
+  "annual": {
+    "1983": {
+      "VND": 1.0
+    },
+    "1986": {
+      "VND": 22.94
+    },
+    "1987": {
+      "VND": 78.95
+    },
+    "1988": {
+      "VND": 611.65
+    },
+    "1989": {
+      "VND": 4501.69
+    },
+    "1990": {
+      "VND": 6537.6
+    },
+    "1991": {
+      "VND": 10121.89
+    },
+    "1992": {
+      "VND": 11202.19
+    },
+    "1993": {
+      "VND": 10640.96
+    },
+    "1994": {
+      "VND": 10965.67
+    },
+    "1995": {
+      "VND": 11038.25
+    },
+    "1996": {
+      "VND": 11032.58
+    },
+    "1997": {
+      "VND": 11683.33
+    },
+    "1998": {
+      "VND": 13268.0
+    },
+    "1999": {
+      "VND": 13943.17
+    },
+    "2000": {
+      "VND": 14167.75
+    },
+    "2001": {
+      "VND": 14725.17
+    },
+    "2002": {
+      "VND": 15279.5
+    },
+    "2003": {
+      "VND": 15509.58
+    },
+    "2004": {
+      "VND": 15746.0
+    },
+    "2005": {
+      "VND": 15858.92
+    },
+    "2006": {
+      "VND": 15994.25
+    },
+    "2007": {
+      "VND": 16105.13
+    },
+    "2008": {
+      "VND": 16302.25
+    },
+    "2009": {
+      "VND": 17065.08
+    },
+    "2010": {
+      "VND": 18612.92
+    },
+    "2011": {
+      "VND": 20509.75
+    },
+    "2012": {
+      "VND": 20828.0
+    },
+    "2013": {
+      "VND": 20933.42
+    },
+    "2014": {
+      "VND": 21148.0
+    },
+    "2015": {
+      "VND": 21697.57
+    },
+    "2016": {
+      "VND": 21935.0
+    },
+    "2017": {
+      "VND": 22370.09
+    },
+    "2018": {
+      "VND": 22602.05
+    },
+    "2019": {
+      "VND": 23050.24
+    },
+    "2020": {
+      "VND": 23208.37
+    },
+    "2021": {
+      "VND": 23159.78
+    },
+    "2022": {
+      "VND": 23271.21
+    },
+    "2023": {
+      "VND": 23787.32
+    },
+    "2024": {
+      "VND": 24164.89
+    }
+  },
+  "base": "USD",
+  "provenance": [
+    {
+      "currencies": [
+        "VND"
+      ],
+      "from": "1983",
+      "provider": "world_bank",
+      "series": "annual",
+      "to": "2024"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "world_bank",
+      "label": "World Bank PA.NUS.FCRF",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 3
+}

data/data/manifest.json

@@ -0,0 +1,90 @@
+{
+  "countries": [
+    {
+      "code": "EU",
+      "cpi_file": "cpi/eu.json",
+      "currency": "EUR",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "JP",
+      "cpi_file": "cpi/jp.json",
+      "currency": "JPY",
+      "granularities": [
+        "annual"
+      ]
+    },
+    {
+      "code": "UK",
+      "cpi_file": "cpi/uk.json",
+      "currency": "GBP",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "US",
+      "cpi_file": "cpi/us.json",
+      "currency": "USD",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "VN",
+      "cpi_file": "cpi/vn.json",
+      "currency": "VND",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    }
+  ],
+  "fx": {
+    "annual_file": "fx/usd/_annual.json",
+    "base": "USD",
+    "currencies": [
+      "EUR",
+      "GBP",
+      "JPY",
+      "VND"
+    ],
+    "daily_years": [
+      1999,
+      2000,
+      2001,
+      2002,
+      2003,
+      2004,
+      2005,
+      2006,
+      2007,
+      2008,
+      2009,
+      2010,
+      2011,
+      2012,
+      2013,
+      2014,
+      2015,
+      2016,
+      2017,
+      2018,
+      2019,
+      2020,
+      2021,
+      2022,
+      2023,
+      2024,
+      2025,
+      2026
+    ]
+  },
+  "generated_at": "2026-05-11",
+  "schema_version": 3
+}

data/lib/timeprice/cli/presenters/compare.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../formatting"
+require_relative "../../granularity"
 
 module Timeprice
   class CLI < Thor
@@ -35,7 +36,8 @@ module Timeprice
             "#{final}  in #{@result.to_date}",
             "  #{original} (#{@result.from_date})",
             format("    -> %-#{width}s -> %s (%s)", step1, converted, @result.from_date),
-            format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date, @result.granularity),
+            format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date,
+                   Granularity.humanize(@result.granularity)),
           ]
         end
       end

data/lib/timeprice/cli/presenters/inflation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../formatting"
+require_relative "../../granularity"
 
 module Timeprice
   class CLI < Thor
@@ -27,7 +28,7 @@ module Timeprice
             format("  %s %s (%s) -> %s %s (%s)",
                    fmt_money(@result.original_amount, @ccy), @ccy, @result.from,
                    fmt_money(@result.amount, @ccy), @ccy, @result.to),
-            "  #{@result.country} · #{@result.granularity} CPI",
+            "  #{@result.country} · #{Granularity.humanize(@result.granularity)} CPI",
           ]
         end
       end

data/lib/timeprice/compare.rb

@@ -5,6 +5,7 @@ require_relative "supported"
 require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
+require_relative "granularity"
 
 module Timeprice
   CompareResult = Data.define(
@@ -37,7 +38,7 @@ module Timeprice
     #   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}
+    # @raise [UnsupportedCurrency] if either currency is not in {Supported.currencies}
     def run(amount:, from:, to:)
       from_point, to_point, to_country = resolve_points(from, to)
 
@@ -70,7 +71,7 @@ module Timeprice
         fx_rate: fx_result.rate,
         cpi_ratio: infl.to_index.to_f / infl.from_index,
         converted_amount: converted,
-        granularity: infl.granularity
+        granularity: Granularity.merge(fx_result.granularity, infl.granularity)
       )
     end
 

data/lib/timeprice/cpi_lookup.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "granularity"
 
 module Timeprice
   # CpiPoint pairs a CPI index value with the granularity of how it was
-  # resolved (monthly, annual, or annual derived by averaging 12 months).
+  # 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
@@ -13,8 +14,8 @@ module Timeprice
   class CpiLookup
     def initialize(data)
       @data = data
-      @monthly = data["monthly"] || {}
-      @annual  = data["annual"]  || {}
+      @monthly = data.dig("series", "monthly") || {}
+      @annual  = data.dig("series", "annual")  || {}
     end
 
     # @param key [String] "YYYY" or "YYYY-MM"
@@ -33,21 +34,22 @@ module Timeprice
     private
 
     def monthly_or_annual_fallback(month_key)
-      return CpiPoint.new(value: @monthly[month_key], granularity: :monthly) if @monthly.key?(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)
 
-      CpiPoint.new(value: @annual[year], granularity: :annual)
+      CpiPoint.new(value: @annual[year], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
 
     def annual_or_monthly_average(year)
-      return CpiPoint.new(value: @annual[year], granularity: :annual) if @annual.key?(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?
 
-      CpiPoint.new(value: months.values.sum.to_f / months.size, granularity: :annual_from_monthly_avg)
+      avg = months.values.sum.to_f / months.size
+      CpiPoint.new(value: avg, granularity: Granularity::ANNUAL_FROM_MONTHLY_AVG)
     end
 
     def missing_message(key)

data/lib/timeprice/data_loader.rb

@@ -2,19 +2,18 @@
 
 require "json"
 require_relative "errors"
-require_relative "supported"
 
 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
+    SUPPORTED_SCHEMA_VERSION = 3
 
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
-      # @return [String] absolute path to the directory containing `cpi/` and `fx/`
+      # @return [String] absolute path to the directory containing `cpi/`, `fx/`, `manifest.json`.
       def data_root
         ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
       end
@@ -32,19 +31,36 @@ module Timeprice
       def clear_cache!
         @cpi_cache = {}
         @fx_cache = {}
+        @manifest_cache = {}
+        @annual_fallback_cache = {}
+      end
+
+      # Load the top-level manifest describing the bundled dataset.
+      # @return [Hash]
+      # @raise [DataNotFound] if `manifest.json` is missing
+      def load_manifest
+        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."
+          end
+
+          parse_with_schema(path)
+        end
       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}
+      # @return [Hash] parsed JSON with "series" / "index" / "provenance" / "providers"
+      # @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)
         key = country.to_s.downcase
         code = country.to_s.upcase
         cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless Supported::COUNTRIES.include?(code)
+          raise UnsupportedCountry, code unless Supported.country?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
@@ -58,7 +74,7 @@ module Timeprice
 
       # Load the FX rates for a year.
       # @param year [Integer, String]
-      # @return [Hash] parsed JSON with a "rates" map of date → currency → Float
+      # @return [Hash] parsed JSON with `rates` (and optional `annual`) blocks
       # @raise [DataNotFound] if the per-year file is missing
       def load_fx_year(year)
         key = year.to_i
@@ -70,6 +86,17 @@ module Timeprice
         end
       end
 
+      # Load the sparse historical FX annual-only fallback file, if present.
+      # Returns nil when no fallback file ships with this data root.
+      # @return [Hash, nil]
+      def load_fx_annual_fallback
+        return @annual_fallback_cache[data_root] if @annual_fallback_cache&.key?(data_root)
+
+        @annual_fallback_cache ||= {}
+        path = File.join(data_root, "fx", "usd", "_annual.json")
+        @annual_fallback_cache[data_root] = File.exist?(path) ? parse_with_schema(path) : nil
+      end
+
       private
 
       def cpi_cache
@@ -80,6 +107,10 @@ module Timeprice
         @fx_cache ||= {}
       end
 
+      def manifest_cache
+        @manifest_cache ||= {}
+      end
+
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]
@@ -90,3 +121,7 @@ module Timeprice
     end
   end
 end
+
+# Supported is loaded by the top-level entry point. Referenced lazily inside
+# load_cpi to avoid a require cycle (Supported reads the manifest via DataLoader).
+require_relative "supported" unless defined?(Timeprice::Supported)

data/lib/timeprice/errors.rb

@@ -7,23 +7,23 @@ module Timeprice
   # to handle anything the gem can throw at you.
   class Error < StandardError; end
 
-  # Raised when a country code is not in {Supported::COUNTRIES}.
+  # 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}.
+  # 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
 

data/lib/timeprice/exchange.rb

@@ -4,10 +4,11 @@ require "date"
 require_relative "errors"
 require_relative "data_loader"
 require_relative "supported"
+require_relative "granularity"
 
 module Timeprice
   ExchangeResult = Data.define(
-    :amount, :original_amount, :from, :to, :date, :effective_date, :rate
+    :amount, :original_amount, :from, :to, :date, :effective_date, :rate, :granularity
   )
 
   # Historical FX conversion using bundled per-year USD-base rate files.
@@ -32,12 +33,12 @@ module Timeprice
     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)
+      raise UnsupportedCurrency, from unless Supported.currency?(from)
+      raise UnsupportedCurrency, to   unless Supported.currency?(to)
 
       d = parse_date(date)
 
-      rate, eff_date = resolve_rate(from, to, d)
+      rate, eff_date, granularity = resolve_rate(from, to, d)
       ExchangeResult.new(
         amount: amount.to_f * rate,
         original_amount: amount.to_f,
@@ -45,40 +46,44 @@ module Timeprice
         to: to,
         date: d.to_s,
         effective_date: eff_date.to_s,
-        rate: rate
+        rate: rate,
+        granularity: granularity
       )
     end
 
-    # Returns [rate (Float), effective_date (Date)].
+    # Returns [rate (Float), effective_date (Date), granularity (Symbol)].
+    # Granularity is :daily when the rate came from a per-date entry, :annual
+    # when it came from the per-year `annual` fallback block. Triangulation
+    # merges both legs via Granularity.merge (worst-precision-wins).
     # 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
+      return [1.0, d, Granularity::DAILY] if from == to
 
       if from == BASE
-        rate, eff = lookup_usd_base(to, d)
-        [rate, eff]
+        lookup_usd_base(to, d)
       elsif to == BASE
-        rate, eff = lookup_usd_base(from, d)
-        [1.0 / rate, eff]
+        rate, eff, gran = lookup_usd_base(from, d)
+        [1.0 / rate, eff, gran]
       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)
+        usd_to_from, eff_a, gran_a = lookup_usd_base(from, d)
+        usd_to_to,   eff_b, gran_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]
+        [usd_to_to / usd_to_from, eff_a, Granularity.merge(gran_a, gran_b)]
       end
     end
 
-    # Walk back up to MAX_FALLBACK_DAYS to find a rate.
-    # Returns [rate, effective_date].
+    # Walk back up to MAX_FALLBACK_DAYS to find a daily rate; if none, fall
+    # back to data/fx/usd/_annual.json (the single source of annual FX truth).
+    # Returns [rate, effective_date, granularity].
     def lookup_usd_base(currency, d)
       (0..MAX_FALLBACK_DAYS).each do |offset|
         candidate = d - offset
@@ -94,11 +99,23 @@ module Timeprice
         rate = rates_for_day[currency]
         next unless rate
 
-        return [rate.to_f, candidate]
+        return [rate.to_f, candidate, Granularity::DAILY]
       end
+
+      annual_rate = annual_fallback(currency, d.year)
+      return [annual_rate, d, Granularity::ANNUAL] if annual_rate
+
       raise DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
     end
 
+    # Consult data/fx/usd/_annual.json. Returns Float or nil.
+    def annual_fallback(currency, year)
+      fallback = DataLoader.load_fx_annual_fallback
+      return nil unless fallback
+
+      fallback.dig("annual", year.to_s, currency)&.to_f
+    end
+
     def parse_date(date)
       case date
       when Date then date