timeprice 0.6.0 → 0.7.0

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/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,6 +23,11 @@ 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
 
@@ -37,16 +43,18 @@ module Timeprice
     # @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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Timeprice
-  VERSION = "0.6.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Patrick
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -107,8 +121,13 @@ files:
 - LICENSE.txt
 - NOTICE
 - README.md
+- data/cpi/au.json
+- data/cpi/ca.json
+- data/cpi/cn.json
 - data/cpi/eu.json
 - data/cpi/jp.json
+- data/cpi/kr.json
+- data/cpi/ru.json
 - data/cpi/uk.json
 - data/cpi/us.json
 - data/cpi/vn.json
@@ -153,11 +172,15 @@ files:
 - lib/timeprice/compare.rb
 - lib/timeprice/cpi_lookup.rb
 - lib/timeprice/data_loader.rb
+- lib/timeprice/date.rb
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
 - lib/timeprice/granularity.rb
 - lib/timeprice/inflation.rb
+- lib/timeprice/metadata.rb
+- lib/timeprice/metadata_snapshot.rb
 - lib/timeprice/point.rb
+- lib/timeprice/schema.rb
 - lib/timeprice/sources.rb
 - lib/timeprice/sources/coverage.rb
 - lib/timeprice/supported.rb