timeprice 0.5.0 → 0.7.0

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

data/lib/timeprice/exchange.rb

@@ -5,6 +5,7 @@ require_relative "errors"
 require_relative "data_loader"
 require_relative "supported"
 require_relative "granularity"
+require_relative "date"
 
 module Timeprice
   ExchangeResult = Data.define(
@@ -15,6 +16,11 @@ module Timeprice
   # 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.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.exchange}. Direct
+  # references will move to `Timeprice::Internal::Exchange` in a future
+  # release.
   module Exchange
     BASE = "USD"
     MAX_FALLBACK_DAYS = 7
@@ -33,8 +39,8 @@ module Timeprice
     def convert(amount:, from:, to:, date:)
       from = from.to_s.upcase
       to   = to.to_s.upcase
-      raise UnsupportedCurrency, from unless Supported.currency?(from)
-      raise UnsupportedCurrency, to   unless Supported.currency?(to)
+      fail UnsupportedCurrency, from unless Supported.currency?(from)
+      fail UnsupportedCurrency, to   unless Supported.currency?(to)
 
       d = parse_date(date)
 
@@ -69,18 +75,32 @@ module Timeprice
         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, 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, Granularity.merge(gran_a, gran_b)]
+        # Triangulation: from → USD → to. Daily legs must agree on the
+        # effective date; an annual leg is valid for any date in its year, so
+        # we adopt the daily leg's date and let Granularity.merge demote.
+        rate_a, *leg_a = lookup_usd_base(from, d)
+        rate_b, *leg_b = lookup_usd_base(to,   d)
+        eff = reconcile_triangulation_dates(from, to, d, leg_a, leg_b)
+        [rate_b / rate_a, eff, Granularity.merge(leg_a[1], leg_b[1])]
       end
     end
 
+    # Pick a single effective date for a triangulated rate. Daily legs must
+    # agree; an annual leg is year-wide so it adopts the daily leg's date.
+    # When both legs are annual we fall back to the requested date.
+    def reconcile_triangulation_dates(from, to, d, leg_a, leg_b)
+      eff_a, gran_a = leg_a
+      eff_b, gran_b = leg_b
+      return eff_a if eff_a == eff_b
+      return d     if gran_a == Granularity::ANNUAL && gran_b == Granularity::ANNUAL
+      return eff_b if gran_a == Granularity::ANNUAL
+      return eff_a if gran_b == Granularity::ANNUAL
+
+      fail DataNotFound,
+           "FX triangulation date mismatch for #{from}->#{to} on #{d}: " \
+           "USD->#{from} resolved #{eff_a}, USD->#{to} resolved #{eff_b}"
+    end
+
     # 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].
@@ -105,7 +125,7 @@ module Timeprice
       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}"
+      fail DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
     end
 
     # Consult data/fx/usd/_annual.json. Returns Float or nil.
@@ -118,20 +138,26 @@ module Timeprice
 
     def parse_date(date)
       case date
-      when Date then date
+      when ::Date
+        date
+      when Timeprice::Date
+        require_daily!(date)
+        ::Date.new(date.year, date.month, date.day)
       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
-
-        begin
-          Date.parse(date)
-        rescue Date::Error
-          raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
-        end
+        parsed = Timeprice::Date.coerce(date)
+        require_daily!(parsed)
+        ::Date.new(parsed.year, parsed.month, parsed.day)
       else
-        raise ArgumentError, "Invalid date: #{date.inspect}"
+        fail ArgumentError, "Invalid date: #{date.inspect}"
       end
+    rescue ::Date::Error
+      raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
+    end
+
+    def require_daily!(date)
+      return if date.granularity == :daily
+
+      fail ArgumentError, "Invalid date: Exchange needs YYYY-MM-DD, got #{date}"
     end
   end
 end

data/lib/timeprice/granularity.rb

@@ -4,20 +4,44 @@ module Timeprice
   # Closed set of CPI-resolution granularities and the rules for combining /
   # rendering them. Owns the lattice so callers don't hand-maintain it.
   module Granularity
-    DAILY                        = :daily
-    MONTHLY                      = :monthly
-    ANNUAL                       = :annual
-    ANNUAL_FROM_MONTHLY_AVG      = :annual_from_monthly_avg
-    MONTHLY_FROM_ANNUAL_FALLBACK = :monthly_from_annual_fallback
+    DAILY                          = :daily
+    MONTHLY                        = :monthly
+    QUARTERLY                      = :quarterly
+    ANNUAL                         = :annual
+    ANNUAL_FROM_MONTHLY_AVG         = :annual_from_monthly_avg
+    ANNUAL_FROM_QUARTERLY_AVG       = :annual_from_quarterly_avg
+    ANNUAL_FROM_PARTIAL_MONTHS      = :annual_from_partial_months
+    ANNUAL_FROM_PARTIAL_QUARTERS    = :annual_from_partial_quarters
+    QUARTERLY_FROM_ANNUAL_FALLBACK  = :quarterly_from_annual_fallback
+    QUARTERLY_FROM_MONTHLY_AVG      = :quarterly_from_monthly_avg
+    MONTHLY_FROM_QUARTERLY_FALLBACK = :monthly_from_quarterly_fallback
+    MONTHLY_FROM_ANNUAL_FALLBACK    = :monthly_from_annual_fallback
 
-    # Most-degraded first — `merge` returns the first match.
-    # DAILY is the highest-precision FX tag; MONTHLY is the highest-precision
-    # CPI tag. Compare uses merge() across both legs, so the most-degraded
-    # tag in either leg wins.
+    # Most-degraded first — `merge` returns the first match. DAILY is the
+    # highest-precision FX tag; MONTHLY is the highest-precision CPI tag.
+    # Compare uses merge() across both legs, so the most-degraded tag in
+    # either leg wins.
+    #
+    # Ordering rationale (worst → best):
+    #   1. Cross-grain fallbacks where the asked resolution is finer than
+    #      what's available (annual stretched to month/quarter).
+    #   2. Partial-period averages — asked annual but only some months/
+    #      quarters in the year are populated. Highly biased by seasonality.
+    #   3. Same-or-coarser fallback (quarter stretched to month).
+    #   4. Full-period derived averages (complete 4-quarter or 12-month mean
+    #      standing in for the asked coarser resolution).
+    #   5. Native series at the asked resolution.
     PRECEDENCE = [
       MONTHLY_FROM_ANNUAL_FALLBACK,
+      ANNUAL_FROM_PARTIAL_QUARTERS,
+      ANNUAL_FROM_PARTIAL_MONTHS,
+      QUARTERLY_FROM_ANNUAL_FALLBACK,
+      MONTHLY_FROM_QUARTERLY_FALLBACK,
+      ANNUAL_FROM_QUARTERLY_AVG,
+      QUARTERLY_FROM_MONTHLY_AVG,
       ANNUAL_FROM_MONTHLY_AVG,
       ANNUAL,
+      QUARTERLY,
       MONTHLY,
       DAILY,
     ].freeze
@@ -25,9 +49,16 @@ module Timeprice
     HUMAN_LABELS = {
       DAILY => "daily",
       MONTHLY => "monthly",
+      QUARTERLY => "quarterly",
       ANNUAL => "annual",
       ANNUAL_FROM_MONTHLY_AVG => "annual (avg of months)",
-      MONTHLY_FROM_ANNUAL_FALLBACK => "annual (month unavailable)",
+      ANNUAL_FROM_QUARTERLY_AVG => "annual (avg of quarters)",
+      ANNUAL_FROM_PARTIAL_MONTHS => "annual (partial-year, avg of available months)",
+      ANNUAL_FROM_PARTIAL_QUARTERS => "annual (partial-year, avg of available quarters)",
+      QUARTERLY_FROM_ANNUAL_FALLBACK => "quarter (annual fallback)",
+      QUARTERLY_FROM_MONTHLY_AVG => "quarter (avg of months)",
+      MONTHLY_FROM_QUARTERLY_FALLBACK => "month (quarter unavailable)",
+      MONTHLY_FROM_ANNUAL_FALLBACK => "month (annual fallback)",
     }.freeze
 
     module_function

data/lib/timeprice/inflation.rb

@@ -4,6 +4,7 @@ require_relative "errors"
 require_relative "data_loader"
 require_relative "cpi_lookup"
 require_relative "granularity"
+require_relative "date"
 
 module Timeprice
   # Value object returned by Inflation.adjust. See {Granularity} for the set
@@ -22,31 +23,38 @@ module Timeprice
   end
 
   # CPI-based inflation adjustment for the {Supported.countries} list.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.inflation}. Direct
+  # references to this module will move to `Timeprice::Internal::Inflation`
+  # in a future release.
   module Inflation
     module_function
 
     # Adjust `amount` from date `from` to date `to` using country CPI.
     #
-    # Dates accept "YYYY" or "YYYY-MM".
+    # Dates accept "YYYY", "YYYY-MM", or "YYYY-Qn" (Q1..Q4).
     #
     # @param amount  [Numeric]
-    # @param from    [String] source date ("YYYY" or "YYYY-MM")
-    # @param to      [String] target date ("YYYY" or "YYYY-MM")
+    # @param from    [String] source date ("YYYY", "YYYY-MM", or "YYYY-Qn")
+    # @param to      [String] target date ("YYYY", "YYYY-MM", or "YYYY-Qn")
     # @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:)
+      from = Timeprice::Date.coerce(from)
+      to   = Timeprice::Date.coerce(to)
       lookup = CpiLookup.new(DataLoader.load_cpi(country))
-      from_point = lookup.at(from)
-      to_point   = lookup.at(to)
+      from_point = lookup.at(from.to_s)
+      to_point   = lookup.at(to.to_s)
 
       ratio = to_point.value.to_f / from_point.value
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
-        from: from,
-        to: to,
+        from: from.to_s,
+        to: to.to_s,
         country: country.to_s.upcase,
         from_index: from_point.value,
         to_index: to_point.value,

data/lib/timeprice/metadata.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "data_loader"
+require_relative "supported"
+require_relative "version"
+require_relative "metadata_snapshot"
+
+module Timeprice
+  # Describes the bundled dataset so external surfaces (the website, other
+  # tools) can render dropdowns, date pickers, and version pills without
+  # hardcoding country lists, currency lists, or date ranges.
+  #
+  # See {Timeprice.metadata} for the public entry point.
+  #
+  # @api private
+  # Direct references will move to `Timeprice::Internal::Metadata` in a
+  # future release.
+  module Metadata
+    # ISO 3166-style display names for the countries shipped today.
+    COUNTRY_NAMES = {
+      "AU" => "Australia",
+      "CA" => "Canada",
+      "CN" => "China",
+      "EU" => "Eurozone",
+      "JP" => "Japan",
+      "KR" => "South Korea",
+      "RU" => "Russia",
+      "UK" => "United Kingdom",
+      "US" => "United States",
+      "VN" => "Vietnam",
+    }.freeze
+
+    # ISO 4217 display names for the currencies shipped today.
+    CURRENCY_NAMES = {
+      "AUD" => "Australian dollar",
+      "CAD" => "Canadian dollar",
+      "CNY" => "Chinese yuan",
+      "EUR" => "Euro",
+      "GBP" => "British pound",
+      "JPY" => "Japanese yen",
+      "KRW" => "South Korean won",
+      "RUB" => "Russian ruble",
+      "USD" => "US dollar",
+      "VND" => "Vietnamese dong",
+    }.freeze
+
+    module_function
+
+    # Build the metadata snapshot.
+    # @return [MetadataSnapshot]
+    def build
+      manifest = DataLoader.load_manifest
+      countries = (manifest["countries"] || []).map { |c| country_entry(c) }
+      currencies = Supported.currencies.map { |code| { code: code, name: CURRENCY_NAMES[code] || code } }
+      MetadataSnapshot.new(
+        version: VERSION,
+        generated_at: manifest["generated_at"],
+        countries: deep_freeze(countries),
+        currencies: deep_freeze(currencies),
+        fx: deep_freeze(fx_entry(manifest))
+      )
+    end
+
+    # Range info comes from the manifest (`cpi_ranges`), pre-computed at
+    # manifest generation time. Falls back to walking the CPI file for any
+    # country missing the field — older manifests, or local data roots
+    # produced by hand.
+    def country_entry(country)
+      code = country["code"]
+      ranges = country["cpi_ranges"] || derive_cpi_ranges(code)
+      per_granularity = ranges.each_with_object({}) do |(gran, range), acc|
+        acc[gran.to_sym] = { min: range["min"], max: range["max"] }
+      end
+      {
+        code: code,
+        name: COUNTRY_NAMES[code] || code,
+        currency: country["currency"],
+        granularities: country["granularities"] || per_granularity.keys.map(&:to_s),
+        cpi: per_granularity,
+      }
+    end
+
+    def derive_cpi_ranges(code)
+      cpi = DataLoader.load_cpi(code)
+      series = cpi["series"] || {}
+      series.each_with_object({}) do |(granularity, points), acc|
+        next unless points.is_a?(Hash) && !points.empty?
+
+        keys = points.keys.sort
+        acc[granularity] = { "min" => keys.first, "max" => keys.last }
+      end
+    end
+
+    # Bounds come from the manifest (`fx.daily_min`/`fx.daily_max`). Older
+    # manifests without those keys: peek at the earliest/latest year files.
+    def fx_entry(manifest)
+      fx = manifest["fx"] || {}
+      base = fx["base"]
+      years = fx["daily_years"] || []
+      return { base: base, daily_min: nil, daily_max: nil } if years.empty?
+
+      daily_min = fx["daily_min"]
+      daily_max = fx["daily_max"]
+      if daily_min.nil? || daily_max.nil?
+        first = DataLoader.load_fx_year(years.min)
+        last  = DataLoader.load_fx_year(years.max)
+        daily_min ||= (first["rates"] || {}).keys.min
+        daily_max ||= (last["rates"] || {}).keys.max
+      end
+      { base: base, daily_min: daily_min, daily_max: daily_max }
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash  then value.each_value { |v| deep_freeze(v) }.freeze
+      when Array then value.each { |v| deep_freeze(v) }.freeze
+      else value.frozen? ? value : value.freeze
+      end
+    end
+  end
+end

data/lib/timeprice/metadata_snapshot.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Timeprice
+  # Frozen value object describing the bundled dataset: version, refresh
+  # date, country list with CPI ranges, currency list with display names,
+  # and FX coverage. Replaces the previous Hash return shape on
+  # {Timeprice.metadata}.
+  #
+  # `[]`, `to_h`, and `to_json` are kept compatible with the old Hash
+  # interface so downstream consumers (the website, this gem's specs)
+  # don't need a coordinated rewrite.
+  MetadataSnapshot = Data.define(:version, :generated_at, :countries, :currencies, :fx) do
+    def [](key)
+      to_h[key]
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/timeprice/point.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "date"
+
 module Timeprice
   # A (currency, date) pair used as input to {Timeprice.compare}.
   #
@@ -13,6 +15,12 @@ module Timeprice
   #   Timeprice::Point.coerce(["USD", "2010"])
   #   Timeprice::Point.coerce(["2010", "USD"])
   Point = Data.define(:currency, :date) do
+    # Canonical constructor. Accepts a stdlib-string or Timeprice::Date
+    # for the date argument; stores the canonical string form.
+    def self.parse(currency, date)
+      new(currency: currency.to_s.upcase, date: Timeprice::Date.coerce(date).to_s)
+    end
+
     # Coerce input into a Point. Accepts:
     #   - {Point} (returned as-is)
     #   - 2-element Array of [currency, date] in either order
@@ -28,11 +36,11 @@ module Timeprice
         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/) }
-        raise ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
+        fail ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
 
         new(currency: currency.upcase, date: date)
       else
-        raise ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
+        fail ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
       end
     end
 
@@ -55,7 +63,7 @@ module Timeprice
       when /\A\d{4}\z/         then "#{date}-06-30"
       when /\A\d{4}-\d{2}\z/   then "#{date}-15"
       when /\A\d{4}-\d{2}-\d{2}\z/ then date.to_s
-      else raise ArgumentError, "Invalid date for Point: #{date.inspect}"
+      else fail ArgumentError, "Invalid date for Point: #{date.inspect}"
       end
     end
   end

data/lib/timeprice/schema.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Timeprice
+  # Single source of truth for the on-disk v4 CPI/manifest format. Both the
+  # reader ({DataLoader}) and the writer (today: pipeline `CountryFile`)
+  # route through here so the schema lives in exactly one place.
+  module Schema
+    CURRENT_VERSION = 4
+    SUPPORTED_VERSIONS = [3, 4].freeze
+
+    KEY_SCHEMA_VERSION = "schema_version"
+    KEY_COUNTRY        = "country"
+    KEY_INDEX          = "index"
+    KEY_SERIES         = "series"
+    KEY_PROVENANCE     = "provenance"
+    KEY_PROVIDERS      = "providers"
+
+    GRANULARITIES = %i[monthly quarterly annual].freeze
+
+    BASE_YEAR_RE = /\A(?<period>.+?)=100(?:\s*\(rebased\s+(?<rebased>\d{4}-\d{2}-\d{2})\))?\z/
+
+    module_function
+
+    def supported?(version)
+      SUPPORTED_VERSIONS.include?(version)
+    end
+
+    def assert_supported!(version, path)
+      return if supported?(version)
+
+      fail UnsupportedSchemaVersion.new(version, path)
+    end
+
+    # Build a CPI payload ready for JSON.dump. Series keys are emitted in a
+    # stable order (annual, monthly[, quarterly]) so file diffs stay tight.
+    def dump_cpi(country:, base_year:, monthly:, annual:, providers:, provenance:, quarterly: {})
+      series = { "annual" => annual, "monthly" => monthly }
+      series["quarterly"] = quarterly unless quarterly.empty?
+      {
+        KEY_SCHEMA_VERSION => CURRENT_VERSION,
+        KEY_COUNTRY => country.to_s.upcase,
+        KEY_INDEX => serialise_base_year(base_year),
+        KEY_SERIES => series,
+        KEY_PROVENANCE => provenance,
+        KEY_PROVIDERS => providers,
+      }
+    end
+
+    # Validate a parsed payload (read from disk) against the schema, then
+    # return it unchanged. Raises UnsupportedSchemaVersion if the version
+    # field is missing or unknown.
+    def load_cpi(parsed, path:)
+      assert_supported!(parsed[KEY_SCHEMA_VERSION], path)
+      parsed
+    end
+
+    def serialise_base_year(str)
+      m = BASE_YEAR_RE.match(str.to_s)
+      if m
+        { "base_period" => m[:period], "rebased_at" => m[:rebased] }
+      else
+        { "base_period" => str.to_s, "rebased_at" => nil }
+      end
+    end
+
+    def deserialise_base_year(index)
+      return nil unless index.is_a?(Hash)
+
+      period = index["base_period"]
+      rebased = index["rebased_at"]
+      return nil if period.nil?
+
+      rebased ? "#{period}=100 (rebased #{rebased})" : "#{period}=100"
+    end
+  end
+end

data/lib/timeprice/supported.rb

@@ -10,7 +10,7 @@ module Timeprice
   module Supported
     # Currencies with no minor unit — formatted as whole numbers. This is
     # ISO 4217 metadata, not bundled data, so it stays hardcoded.
-    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+    ZERO_DECIMAL_CURRENCIES = %w[JPY KRW VND].freeze
 
     module_function
 

data/lib/timeprice/version.rb

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

data/lib/timeprice.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "timeprice/version"
+require_relative "timeprice/errors"
+require_relative "timeprice/schema"
+require_relative "timeprice/date"
 require_relative "timeprice/data_loader"
 require_relative "timeprice/supported"
-require_relative "timeprice/errors"
 require_relative "timeprice/point"
 require_relative "timeprice/inflation"
 require_relative "timeprice/exchange"
 require_relative "timeprice/compare"
 require_relative "timeprice/sources"
+require_relative "timeprice/metadata"
 
 # Offline historical inflation & FX for Ruby.
 #
@@ -62,4 +65,14 @@ module Timeprice
   def compare(amount:, from:, to:)
     Compare.run(amount: amount, from: from, to: to)
   end
+
+  # Snapshot describing the bundled dataset: version, refresh date, country
+  # list with CPI ranges, currency list with display names, and FX coverage.
+  # Intended as the single source of truth for downstream UIs (the website
+  # in particular) so dropdowns and date pickers never drift from the data.
+  #
+  # @return [Hash] frozen, JSON-serialisable
+  def metadata
+    Metadata.build
+  end
 end