timeprice 0.1.0

data/data/fx/usd/2026.json

@@ -0,0 +1,449 @@
+{
+  "base": "USD",
+  "rates": {
+    "2026-01-02": {
+      "EUR": 0.85317,
+      "GBP": 0.74388,
+      "JPY": 156.93
+    },
+    "2026-01-05": {
+      "EUR": 0.85734,
+      "GBP": 0.74383,
+      "JPY": 156.83
+    },
+    "2026-01-06": {
+      "EUR": 0.85419,
+      "GBP": 0.73998,
+      "JPY": 156.44
+    },
+    "2026-01-07": {
+      "EUR": 0.85587,
+      "GBP": 0.74153,
+      "JPY": 156.55
+    },
+    "2026-01-08": {
+      "EUR": 0.85653,
+      "GBP": 0.74407,
+      "JPY": 156.72
+    },
+    "2026-01-09": {
+      "EUR": 0.85896,
+      "GBP": 0.74532,
+      "JPY": 157.64
+    },
+    "2026-01-12": {
+      "EUR": 0.85529,
+      "GBP": 0.74187,
+      "JPY": 157.73
+    },
+    "2026-01-13": {
+      "EUR": 0.85807,
+      "GBP": 0.74309,
+      "JPY": 158.85
+    },
+    "2026-01-14": {
+      "EUR": 0.8583,
+      "GBP": 0.74397,
+      "JPY": 158.63
+    },
+    "2026-01-15": {
+      "EUR": 0.86029,
+      "GBP": 0.74621,
+      "JPY": 158.56
+    },
+    "2026-01-16": {
+      "EUR": 0.86081,
+      "GBP": 0.74632,
+      "JPY": 158.1
+    },
+    "2026-01-19": {
+      "EUR": 0.85977,
+      "GBP": 0.74551,
+      "JPY": 157.93
+    },
+    "2026-01-20": {
+      "EUR": 0.85266,
+      "GBP": 0.74369,
+      "JPY": 157.9
+    },
+    "2026-01-21": {
+      "EUR": 0.85186,
+      "GBP": 0.74487,
+      "JPY": 157.79
+    },
+    "2026-01-22": {
+      "EUR": 0.85426,
+      "GBP": 0.74509,
+      "JPY": 158.79
+    },
+    "2026-01-23": {
+      "EUR": 0.85164,
+      "GBP": 0.73931,
+      "JPY": 158.16
+    },
+    "2026-01-26": {
+      "EUR": 0.84488,
+      "GBP": 0.73293,
+      "JPY": 154.21
+    },
+    "2026-01-27": {
+      "EUR": 0.83829,
+      "GBP": 0.72789,
+      "JPY": 153.34
+    },
+    "2026-01-28": {
+      "EUR": 0.83514,
+      "GBP": 0.72532,
+      "JPY": 152.63
+    },
+    "2026-01-29": {
+      "EUR": 0.83556,
+      "GBP": 0.72376,
+      "JPY": 153.31
+    },
+    "2026-01-30": {
+      "EUR": 0.839,
+      "GBP": 0.72674,
+      "JPY": 154.03
+    },
+    "2026-02-02": {
+      "EUR": 0.84459,
+      "GBP": 0.73125,
+      "JPY": 155.06
+    },
+    "2026-02-03": {
+      "EUR": 0.84739,
+      "GBP": 0.7307,
+      "JPY": 155.85
+    },
+    "2026-02-04": {
+      "EUR": 0.84602,
+      "GBP": 0.72893,
+      "JPY": 156.64
+    },
+    "2026-02-05": {
+      "EUR": 0.8476,
+      "GBP": 0.73665,
+      "JPY": 156.9
+    },
+    "2026-02-06": {
+      "EUR": 0.84789,
+      "GBP": 0.73588,
+      "JPY": 157.09
+    },
+    "2026-02-09": {
+      "EUR": 0.84133,
+      "GBP": 0.73204,
+      "JPY": 156.19
+    },
+    "2026-02-10": {
+      "EUR": 0.84076,
+      "GBP": 0.73104,
+      "JPY": 155.13
+    },
+    "2026-02-11": {
+      "EUR": 0.84034,
+      "GBP": 0.73101,
+      "JPY": 153.61
+    },
+    "2026-02-12": {
+      "EUR": 0.84218,
+      "GBP": 0.73362,
+      "JPY": 153.71
+    },
+    "2026-02-13": {
+      "EUR": 0.84303,
+      "GBP": 0.73478,
+      "JPY": 153.29
+    },
+    "2026-02-16": {
+      "EUR": 0.84353,
+      "GBP": 0.73302,
+      "JPY": 153.34
+    },
+    "2026-02-17": {
+      "EUR": 0.84559,
+      "GBP": 0.73846,
+      "JPY": 153.1
+    },
+    "2026-02-18": {
+      "EUR": 0.84424,
+      "GBP": 0.73651,
+      "JPY": 153.64
+    },
+    "2026-02-19": {
+      "EUR": 0.85085,
+      "GBP": 0.74347,
+      "JPY": 154.9
+    },
+    "2026-02-20": {
+      "EUR": 0.84983,
+      "GBP": 0.74174,
+      "JPY": 155.21
+    },
+    "2026-02-23": {
+      "EUR": 0.84861,
+      "GBP": 0.74117,
+      "JPY": 154.82
+    },
+    "2026-02-24": {
+      "EUR": 0.84911,
+      "GBP": 0.74136,
+      "JPY": 155.84
+    },
+    "2026-02-25": {
+      "EUR": 0.84861,
+      "GBP": 0.73948,
+      "JPY": 156.74
+    },
+    "2026-02-26": {
+      "EUR": 0.84645,
+      "GBP": 0.73802,
+      "JPY": 156.06
+    },
+    "2026-02-27": {
+      "EUR": 0.8471,
+      "GBP": 0.74231,
+      "JPY": 155.98
+    },
+    "2026-03-02": {
+      "EUR": 0.85485,
+      "GBP": 0.74705,
+      "JPY": 157.45
+    },
+    "2026-03-03": {
+      "EUR": 0.86162,
+      "GBP": 0.75108,
+      "JPY": 157.66
+    },
+    "2026-03-04": {
+      "EUR": 0.85844,
+      "GBP": 0.74727,
+      "JPY": 157.11
+    },
+    "2026-03-05": {
+      "EUR": 0.86073,
+      "GBP": 0.74841,
+      "JPY": 157.54
+    },
+    "2026-03-06": {
+      "EUR": 0.86498,
+      "GBP": 0.74987,
+      "JPY": 157.92
+    },
+    "2026-03-09": {
+      "EUR": 0.86543,
+      "GBP": 0.74885,
+      "JPY": 158.5
+    },
+    "2026-03-10": {
+      "EUR": 0.85903,
+      "GBP": 0.74345,
+      "JPY": 157.78
+    },
+    "2026-03-11": {
+      "EUR": 0.86348,
+      "GBP": 0.74573,
+      "JPY": 158.56
+    },
+    "2026-03-12": {
+      "EUR": 0.86603,
+      "GBP": 0.74689,
+      "JPY": 158.86
+    },
+    "2026-03-13": {
+      "EUR": 0.87138,
+      "GBP": 0.75377,
+      "JPY": 159.33
+    },
+    "2026-03-16": {
+      "EUR": 0.87123,
+      "GBP": 0.75281,
+      "JPY": 159.14
+    },
+    "2026-03-17": {
+      "EUR": 0.86723,
+      "GBP": 0.74954,
+      "JPY": 158.95
+    },
+    "2026-03-18": {
+      "EUR": 0.86957,
+      "GBP": 0.75124,
+      "JPY": 159.56
+    },
+    "2026-03-19": {
+      "EUR": 0.8704,
+      "GBP": 0.75192,
+      "JPY": 158.81
+    },
+    "2026-03-20": {
+      "EUR": 0.86543,
+      "GBP": 0.74806,
+      "JPY": 158.77
+    },
+    "2026-03-23": {
+      "EUR": 0.86237,
+      "GBP": 0.74526,
+      "JPY": 158.55
+    },
+    "2026-03-24": {
+      "EUR": 0.86415,
+      "GBP": 0.74785,
+      "JPY": 158.93
+    },
+    "2026-03-25": {
+      "EUR": 0.86266,
+      "GBP": 0.7467,
+      "JPY": 158.96
+    },
+    "2026-03-26": {
+      "EUR": 0.86663,
+      "GBP": 0.74976,
+      "JPY": 159.62
+    },
+    "2026-03-27": {
+      "EUR": 0.86828,
+      "GBP": 0.75297,
+      "JPY": 159.9
+    },
+    "2026-03-30": {
+      "EUR": 0.87078,
+      "GBP": 0.75586,
+      "JPY": 159.46
+    },
+    "2026-03-31": {
+      "EUR": 0.86972,
+      "GBP": 0.7552,
+      "JPY": 159.5
+    },
+    "2026-04-01": {
+      "EUR": 0.8617,
+      "GBP": 0.75065,
+      "JPY": 158.32
+    },
+    "2026-04-02": {
+      "EUR": 0.86768,
+      "GBP": 0.75708,
+      "JPY": 159.6
+    },
+    "2026-04-07": {
+      "EUR": 0.86528,
+      "GBP": 0.75502,
+      "JPY": 159.84
+    },
+    "2026-04-08": {
+      "EUR": 0.85426,
+      "GBP": 0.74229,
+      "JPY": 158.15
+    },
+    "2026-04-09": {
+      "EUR": 0.8558,
+      "GBP": 0.745,
+      "JPY": 158.92
+    },
+    "2026-04-10": {
+      "EUR": 0.8539,
+      "GBP": 0.74379,
+      "JPY": 159.19
+    },
+    "2026-04-13": {
+      "EUR": 0.85587,
+      "GBP": 0.7451,
+      "JPY": 159.83
+    },
+    "2026-04-14": {
+      "EUR": 0.84796,
+      "GBP": 0.73699,
+      "JPY": 158.85
+    },
+    "2026-04-15": {
+      "EUR": 0.8489,
+      "GBP": 0.73799,
+      "JPY": 159.09
+    },
+    "2026-04-16": {
+      "EUR": 0.84875,
+      "GBP": 0.73836,
+      "JPY": 158.98
+    },
+    "2026-04-17": {
+      "EUR": 0.84767,
+      "GBP": 0.7389,
+      "JPY": 159.13
+    },
+    "2026-04-20": {
+      "EUR": 0.85034,
+      "GBP": 0.74018,
+      "JPY": 158.91
+    },
+    "2026-04-21": {
+      "EUR": 0.84983,
+      "GBP": 0.73965,
+      "JPY": 159.04
+    },
+    "2026-04-22": {
+      "EUR": 0.8523,
+      "GBP": 0.74067,
+      "JPY": 159.22
+    },
+    "2026-04-23": {
+      "EUR": 0.85514,
+      "GBP": 0.74034,
+      "JPY": 159.48
+    },
+    "2026-04-24": {
+      "EUR": 0.85383,
+      "GBP": 0.74115,
+      "JPY": 159.42
+    },
+    "2026-04-27": {
+      "EUR": 0.85114,
+      "GBP": 0.73691,
+      "JPY": 159.21
+    },
+    "2026-04-28": {
+      "EUR": 0.85616,
+      "GBP": 0.74242,
+      "JPY": 159.74
+    },
+    "2026-04-29": {
+      "EUR": 0.85426,
+      "GBP": 0.74016,
+      "JPY": 159.79
+    },
+    "2026-04-30": {
+      "EUR": 0.85455,
+      "GBP": 0.74026,
+      "JPY": 156.56
+    },
+    "2026-05-04": {
+      "EUR": 0.8547,
+      "GBP": 0.7381,
+      "JPY": 157.12
+    },
+    "2026-05-05": {
+      "EUR": 0.85572,
+      "GBP": 0.73886,
+      "JPY": 157.81
+    },
+    "2026-05-06": {
+      "EUR": 0.8502,
+      "GBP": 0.73431,
+      "JPY": 156.21
+    },
+    "2026-05-07": {
+      "EUR": 0.84962,
+      "GBP": 0.73415,
+      "JPY": 156.39
+    },
+    "2026-05-08": {
+      "EUR": 0.85027,
+      "GBP": 0.73472,
+      "JPY": 156.76
+    }
+  },
+  "schema_version": 1,
+  "source": "Frankfurter (ECB) — daily reference rates",
+  "updated_at": "2026-05-11",
+  "year": 2026
+}

data/exe/timeprice

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "timeprice"
+require "timeprice/cli"
+
+Timeprice::CLI.start(ARGV)

data/lib/timeprice/cli.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+require_relative "../timeprice"
+
+module Timeprice
+  class CLI < Thor
+    class_option :json, type: :boolean, default: false, desc: "Output result as JSON"
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "inflation AMOUNT", "Adjust AMOUNT for inflation 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)"
+    def inflation(amount)
+      with_error_handling do
+        result = Timeprice.inflation(
+          amount: Float(amount),
+          from: options[:from],
+          to: options[:to],
+          country: options[:country]
+        )
+        emit_inflation(result)
+      end
+    end
+
+    desc "fx AMOUNT FROM_CURRENCY TO_CURRENCY", "Convert AMOUNT between currencies on a given date"
+    method_option :date, type: :string, required: true, desc: "Date (YYYY-MM-DD)"
+    def fx(amount, from_currency, to_currency)
+      with_error_handling do
+        result = Timeprice.exchange(
+          amount: Float(amount),
+          from: from_currency,
+          to: to_currency,
+          date: options[:date]
+        )
+        emit_exchange(result)
+      end
+    end
+
+    desc "compare AMOUNT", "Combine FX + inflation across two (year, currency) points"
+    method_option :from, type: :string, required: true, desc: "Source as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :to,   type: :string, required: true, desc: "Target as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    def compare(amount)
+      with_error_handling do
+        from_tuple = parse_compare_token(options[:from], label: "--from")
+        to_tuple   = parse_compare_token(options[:to],   label: "--to")
+        result = Timeprice.compare(
+          amount: Float(amount),
+          from: from_tuple,
+          to: to_tuple
+        )
+        emit_compare(result)
+      end
+    end
+
+    desc "sources", "List bundled data sources, licenses, attribution, and coverage"
+    def sources
+      list = Timeprice::Sources.list
+      if options[:json]
+        say JSON.generate(list)
+      else
+        list.each do |s|
+          say "#{s[:name]}"
+          say "  id:           #{s[:id]}"
+          say "  license:      #{s[:license]}"
+          say "  license_url:  #{s[:license_url]}"
+          say "  attribution:  #{s[:attribution]}"
+          say "  coverage:     #{s[:coverage]}"
+          say ""
+        end
+      end
+    end
+
+    desc "version", "Print the installed timeprice version"
+    def version
+      if options[:json]
+        say JSON.generate({ version: Timeprice::VERSION, repo: "patrick204nqh/timeprice" })
+      else
+        say "timeprice #{Timeprice::VERSION} — patrick204nqh/timeprice"
+      end
+    end
+
+    no_commands do
+      def with_error_handling
+        yield
+      rescue Timeprice::Error => e
+        warn "Error: #{e.message}"
+        exit 1
+      rescue ArgumentError => e
+        # Bad numeric/date format from Float() or library parsers — treat as user error.
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      # Accepts "1995 USD" or "USD 1995" — order-agnostic.
+      # Returns [currency, year_string] tuple matching Timeprice.compare's API.
+      def parse_compare_token(token, label:)
+        raise 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}"
+        end
+        year = parts.find { |p| p.match?(/\A\d{4}\z/) }
+        currency = parts.find { |p| p.match?(/\A[A-Za-z]{3}\z/) }
+        if year.nil? || currency.nil?
+          raise ArgumentError,
+                "#{label} must contain a 4-digit year and a 3-letter currency code, got #{token.inspect}"
+        end
+        [currency.upcase, year]
+      end
+
+      def emit_inflation(result)
+        if options[:json]
+          say JSON.generate(result.to_h)
+        else
+          say format(
+            "%.2f %s in %s is %.2f %s in %s (%s, granularity: %s)",
+            result.original_amount, result.country_currency_label,
+            result.from, result.amount, result.country_currency_label,
+            result.to, result.country, result.granularity
+          )
+        end
+      end
+
+      def emit_exchange(result)
+        if options[:json]
+          say JSON.generate(result.to_h)
+        else
+          line = format(
+            "%.2f %s on %s = %.2f %s (rate: %.4f)",
+            result.original_amount, result.from, result.date,
+            result.amount, result.to, result.rate
+          )
+          if result.effective_date && result.effective_date != result.date
+            line += " (effective date: #{result.effective_date} — fallback)"
+          end
+          say line
+        end
+      end
+
+      def emit_compare(result)
+        if options[:json]
+          say JSON.generate(result.to_h)
+        else
+          say format(
+            "%.2f %s in %s -> %.2f %s in %s",
+            result.original_amount, result.from_currency, result.from_date,
+            result.amount, result.to_currency, result.to_date
+          )
+          say format(
+            "  steps: convert at %s (fx rate %.6f) -> %.4f %s, then inflate in %s (cpi ratio %.6f, granularity: %s)",
+            result.from_date, result.fx_rate, result.converted_amount,
+            result.to_currency, result.country, result.cpi_ratio, result.granularity
+          )
+        end
+      end
+    end
+  end
+end
+
+# Tiny shim so we can include currency context in the inflation line without
+# bloating the value object — the result doesn't carry currency, only country.
+module Timeprice
+  class InflationResult
+    COUNTRY_TO_CURRENCY = {
+      "US" => "USD", "UK" => "GBP", "EU" => "EUR", "JP" => "JPY", "VN" => "VND"
+    }.freeze
+
+    def country_currency_label
+      COUNTRY_TO_CURRENCY[country.to_s.upcase] || country.to_s.upcase
+    end
+  end
+end