timeprice 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91644504f73e6324d522d189233539a5515ca51cf0be58b1a34da90ff78220d
-  data.tar.gz: f6120dc38bb433e1dc8ac56e523b3c547d9323b578f34a27bddee3e43b48c9a2
+  metadata.gz: 5f350843e8e12653e2f798d8f9afec193001e911e0f36910d0473724f33d79f8
+  data.tar.gz: 3d1107eb101dd95ec6c2203fe6f1843f9249cf5046cf838577094c67a0fe63c0
 SHA512:
-  metadata.gz: b8b0f99a9962bad944a02499761a586e860d50a3707e70de4d1549c6bf624ea5bf1a9d1d2beae488abdfc6646d825320259a196bfac177e64c25edab90e721e5
-  data.tar.gz: 54bb2545e7c9f9bbdb202994f3d5f53bb020a36bde0a2d8627c734a1c0e4312fcbe0237ce2b23409af9253ddc809ae74129dec43b17b94c559bcefa8917142cf
+  metadata.gz: a7efbb6d151b4fd4c9c6d4697fc9c755c9a0d2e6b8e1e32d828a1416737dbfbd00d9143c64edde191eaea3f7f758b96ac1d4b93c9f765fbc5d0993bf68b0be7a
+  data.tar.gz: 3a5b598b62cf93b992ed4ba5d069f84475c91a0be636600451fb3247caaa5c494c44b39268ed5e6107c34f923606521d42374d3300de42ad5a7449f53ae37e39

data/CHANGELOG.md

@@ -5,6 +5,58 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-12
+
+### Added
+- **Five new countries: AU, CA, KR, CN, RU.** CPI + FX coverage:
+  - AU (Australia): quarterly CPI from ABS 6401.0, annual baseline from World
+    Bank `FP.CPI.TOTL`; AUD daily FX from Frankfurter.
+  - CA (Canada): monthly CPI from Statistics Canada WDS (table 18-10-0004-01),
+    annual baseline from World Bank; CAD daily FX from Frankfurter.
+  - KR (Korea, Rep.): monthly CPI from IMF Data Portal CPI dataflow, annual
+    baseline from World Bank; KRW daily FX from Frankfurter. (KOSIS Open API
+    is a future upgrade path — see `scripts/sources/kosis.rb`.)
+  - CN (China): annual CPI from World Bank, monthly layered from IMF Data
+    Portal; CNY daily FX from Frankfurter.
+  - RU (Russia): annual CPI from World Bank, monthly layered from IMF; RUB FX
+    from IMF IFS `ENDA_XDC_USD_RATE` written as annual averages to
+    `_annual.json` (Frankfurter dropped RUB after the ECB suspended reference
+    rates in March 2022, so daily RUB is intentionally not bundled).
+- `KRW` added to `Supported::ZERO_DECIMAL_CURRENCIES`.
+
+### Changed
+- **Schema v3 → v4.** Backward-compatible bump:
+  - CPI files gain an optional `series.quarterly` block (keyed `YYYY-Qn`)
+    alongside `series.monthly` and `series.annual`. Files without quarterly
+    data are byte-identical to v3 layout other than the version field.
+  - `DataLoader` accepts both v3 and v4 files; new writes are v4.
+  - `Granularity` gains `:quarterly`, `:annual_from_quarterly_avg`,
+    `:quarterly_from_annual_fallback`, and `:monthly_from_quarterly_fallback`.
+    `CpiLookup` resolves "YYYY-Qn" keys and falls back monthly → quarterly →
+    annual.
+
+## [0.5.0] - 2026-05-11
+
+### Changed
+- **Schema v2 → v3.** Breaking change to the bundled data contract. v0.4.x
+  data files will not load on v0.5.0.
+  - New top-level `data/manifest.json` — single source of truth for which
+    countries and currencies the bundle supports. `Supported.countries` /
+    `Supported.currencies` derive from it at runtime; the hardcoded Ruby
+    constants `Supported::COUNTRIES` / `CURRENCIES` are gone. Custom callers
+    that referenced those constants must switch to the method form.
+  - CPI files use nested `series: { monthly, annual }` and a structured
+    `index: { base_period, rebased_at }` block in place of the freeform
+    `base_year` string. Top-level `source` and `updated_at` removed —
+    `providers[]` is the source of truth for provenance.
+  - FX year files now carry `provenance` + `providers` blocks, symmetric
+    with CPI.
+  - All annual FX (today only VND from World Bank) lives in
+    `data/fx/usd/_annual.json` — the single canonical source, every year.
+    Per-year files (`data/fx/usd/<year>.json`) hold daily rates only. Pre-1999
+    stub year files are gone. `Exchange.lookup_usd_base` collapses to a
+    two-tier chain (daily → annual fallback), one source per tier.
+
 ## [0.4.0] - 2026-05-11
 
 ### Changed

data/DATA_LICENSES.md

@@ -14,8 +14,15 @@ string.
 | World Bank | `FP.CPI.TOTL` (JP CPI fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 | World Bank | `FP.CPI.TOTL` (VN CPI, annual fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 | International Monetary Fund | CPI dataflow `VNM.CPI._T.IX.M` via IMF Data Portal (VN CPI, monthly primary) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
-| European Central Bank (via Frankfurter) | Daily reference rates, USD base, EUR/GBP/JPY | ECB reference rates — free reuse; Frankfurter is a non-commercial republisher with no separate license | https://www.ecb.europa.eu/services/disclaimer/html/index.en.html | FX data: European Central Bank reference rates via Frankfurter |
+| European Central Bank (via Frankfurter) | Daily reference rates, USD base, EUR/GBP/JPY/AUD/CAD/KRW/CNY | ECB reference rates — free reuse; Frankfurter is a non-commercial republisher with no separate license | https://www.ecb.europa.eu/services/disclaimer/html/index.en.html | FX data: European Central Bank reference rates via Frankfurter |
 | World Bank | `PA.NUS.FCRF` (VND annual average FX, broadcast daily) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | VND FX: World Bank, PA.NUS.FCRF |
+| Australian Bureau of Statistics | `CPI` dataflow, key `3.10001.10.50.Q` (AU CPI, quarterly, all groups, weighted average of eight capital cities) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://www.abs.gov.au/website-privacy-copyright-and-disclaimer/copyright-and-creative-commons | Source: Australian Bureau of Statistics, 6401.0 Consumer Price Index |
+| Statistics Canada | Table 18-10-0004-01, vector `v41690973` (CA CPI, monthly, all-items, not seasonally adjusted) | Statistics Canada Open License | https://www.statcan.gc.ca/en/reference/licence | Source: Statistics Canada, table 18-10-0004-01 |
+| International Monetary Fund | CPI dataflow `KOR.CPI._T.IX.M` (KR CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | CPI dataflow `CHN.CPI._T.IX.M` (CN CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | CPI dataflow `RUS.CPI._T.IX.M` (RU CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | IFS dataflow `M.RUS.ENDA_XDC_USD_RATE` (RUB/USD, period-average, annual mean written to `_annual.json`) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF International Financial Statistics |
+| World Bank | `FP.CPI.TOTL` (AU/CA/KR/CN/RU CPI annual baselines) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 
 ## Notes
 
@@ -25,6 +32,14 @@ string.
 - The Vietnam VND FX series is the **annual average** broadcast to every day in
   the year — it is intentionally not a daily market rate. Do not use it for
   intraday or trade-execution purposes.
+- **RUB FX is annual-only** (from IMF IFS period averages). Frankfurter (ECB)
+  stopped publishing RUB daily reference rates in March 2022 after the ECB
+  suspended the rate, and no other free, no-API-key daily source covers the
+  full series. Daily RUB lookups fall back to the annual average and the
+  result is tagged so consumers can detect the degradation.
+- **AU CPI is published quarterly only.** Lookups against "YYYY-MM" keys for
+  Australia fall back to the quarter that contains the month, and the result
+  is tagged `:monthly_from_quarterly_fallback`.
 - Eurostat HICP is harmonized across the Eurozone and is **not** the same as
   any national CPI. We use it for the `EU` country code; national CPIs are out
   of scope for v0.1.

data/README.md

@@ -99,10 +99,19 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | Eurozone (EA) | EUR | Eurostat HICP (`prc_hicp_midx`) | Monthly + annual | 1996-01 → present |
 | Japan | JPY | World Bank `FP.CPI.TOTL` (fallback) | Annual | 1960 → 2024 |
 | Vietnam | VND | IMF Data Portal CPI dataflow (monthly primary) + World Bank `FP.CPI.TOTL` (annual fallback) | Monthly + annual | 1995 → present |
-
-**FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY**, daily
-1999 → present. **VND** uses the World Bank annual average (`PA.NUS.FCRF`) broadcast to
-every day in the year, from 1983 → present.
+| Australia | AUD | ABS 6401.0 (quarterly) + World Bank `FP.CPI.TOTL` (annual baseline) | Quarterly + annual | 1948-Q3 → present |
+| Canada | CAD | Statistics Canada WDS (table 18-10-0004-01, vector `v41690973`) + World Bank annual baseline | Monthly + annual | 1914-01 → present |
+| Korea (Rep.) | KRW | IMF Data Portal CPI dataflow + World Bank annual baseline | Monthly + annual | 1990-01 → present |
+| China | CNY | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1990-01 → present |
+| Russia | RUB | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1992-01 → present |
+
+**FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY / AUD /
+CAD / KRW / CNY**, daily 1999 → present. **VND** uses the World Bank annual average
+(`PA.NUS.FCRF`), one value per year, from 1983 → present. **RUB** uses IMF IFS
+period-average rates as annual means (`ENDA_XDC_USD_RATE`) — Frankfurter dropped RUB
+after the ECB suspended its reference rate in March 2022, so daily RUB is intentionally
+not bundled. Annual-fallback results (VND, RUB) are tagged `granularity: :annual` so
+callers know they did not get a daily rate.
 
 Triangulated cross-rates (e.g. GBP → JPY) go through USD on the same effective date.
 Weekend/holiday dates fall back up to 7 days to the nearest prior trading day.
@@ -222,7 +231,7 @@ namespace :inflation do
   desc "Print 1990→today inflation for the supported countries"
   task :report do
     today = Date.today.strftime("%Y-%m")
-    %w[US UK EU JP VN].each do |c|
+    %w[US UK EU JP VN AU CA KR CN RU].each do |c|
       r = Timeprice.inflation(amount: 100, from: "1990", to: today, country: c)
       puts "#{c}: 100 in 1990 → #{r.amount.round(2)} in #{today} (#{r.granularity})"
     end
@@ -265,6 +274,21 @@ license — see `DATA_LICENSES.md` and `NOTICE` for the full table and license U
 If you redistribute results derived from this gem, reproduce the relevant attribution
 strings. `timeprice sources` prints them in plain text and as JSON.
 
+## Data format
+
+Bundled data lives under `data/` in schema v3 and is self-describing:
+
+- `data/manifest.json` — the supported set (countries, currencies, FX years).
+- `data/cpi/<country>.json` — CPI for one country: `series.{monthly,annual}`,
+  structured `index` block, `provenance` ranges, `providers` attribution.
+- `data/fx/usd/<year>.json` — daily USD-base FX rates for one year (one file
+  per year, EUR/GBP/JPY).
+- `data/fx/usd/_annual.json` — annual USD-base FX rates across all years for
+  currencies sourced at annual resolution (today only VND). Used as the
+  fallback tier when no daily rate covers the requested date.
+
+`scripts/check_schema_stability.rb` enforces the shape in CI.
+
 ## Author
 
 Built by [Patrick](https://github.com/patrick204nqh).