Add @suaveplan/currency-providers — concrete CurrencyProvider plugins

Package: @suaveplan/currency-providers Status: PROPOSED Type: migration (upstream ../suaveplan/packages/finance/currency-providers)

Design: ./design.md
Spec delta: ./specs/currency-providers/spec.md

Why

STATUS.md lists @suaveplan/currency-providers as Pending. With @suaveplan/currency shipped on genesis (2026-05-17), the provider plugins are the next link in the commerce chain: they are the concrete CurrencyProvider implementations that real applications wire into CurrencyConverter. Every fiat conversion (ECB / Fixer / Open Exchange Rates), every crypto quote (CoinGecko / CoinMarketCap / Binance / Kraken / CryptoCompare), and every operator-defined virtual-currency (game gold, gems, etc.) depends on this package. Without it, @suaveplan/currency is an empty engine; with it, the commerce stack has rate data flowing end-to-end.

The migration preserves the upstream public surface verbatim — same provider class names, same config shapes (ApiKeyConfig / NoKeyConfig), same fetchRates semantics — and lifts the package to the genesis quality bar: every plain throw new Error(...) becomes a typed CurrencyProviderError carrying a stable CURRENCY_PROVIDER.* code; HTTP is performed through an injectable FetchLike (default globalThis.fetch) so tests are real fakes not mocks; every provider is universal-tier with zero browser/Node APIs; folder layout matches the §10 no-prefix rule (providers/ecb/ecb.ts, not providers/ecb-provider/ecb-provider.ts); every implementation file has a sibling .md; every public module has a subpath export.

The enterprise audit (../suaveplan/enterprise/currency-providers.md) lists nine "feature-rich enhancements" — rate-limited wrappers, historical-rate endpoints, WebSocket streaming, on-chain oracles, aggregator providers, health monitors, multi-base normalization, deterministic replay, SLO tracking. Those land in follow-up changes once their dependency packages (@suaveplan/retry, @suaveplan/rate-limiter, @suaveplan/events, @suaveplan/cryptocurrency's chain registry) are wired through this surface; the migration baseline matches the upstream behaviour bit-for-bit, fills the three test-coverage gaps the audit flagged (Fixer / OXR / CoinMarketCap had no tests upstream), and unblocks every downstream commerce consumer.

What changes

ADDED: EcbProvider — ECB daily XML feed, no API key, EUR-base with automatic conversion to any requested base.
ADDED: FixerProvider — Fixer.io API, requires apiKey, EUR-base on free tier.
ADDED: OpenExchangeRatesProvider — OXR API, requires apiKey, USD-base on free tier, supports targets filtering.
ADDED: BinanceProvider — Binance spot ticker, no API key, USDT-base by default, real-time prices.
ADDED: CoinGeckoProvider + getCoinGeckoId helper — CoinGecko simple/price endpoint, no API key, 16-symbol built-in registry.
ADDED: CoinMarketCapProvider — CMC cryptocurrency/quotes/latest, requires apiKey, supports configurable target symbols.
ADDED: CryptoCompareProvider — CryptoCompare pricemulti, no API key, 15-symbol default list.
ADDED: KrakenProvider — Kraken Ticker, no API key, maps Kraken's non-standard pair names back to canonical symbols.
ADDED: VirtualCurrencyProvider — operator-defined game / virtual currencies with runtime addCurrency / updateRate / removeCurrency / getRate / getCurrencyCodes, anchored against a fiat base, registers every currency with @suaveplan/money's currency registry.
ADDED: ApiKeyConfig / NoKeyConfig / HttpFetchOptions config types (named interfaces, no inline shapes per AGENTS.md §11).
ADDED: FetchLike injection on every provider — every fetchRates implementation accepts an optional fetch in its constructor config, defaulting to globalThis.fetch. Tests inject a custom FetchLike instead of mocking globals.
ADDED: CURRENCY_PROVIDER_CODES registry via defineCodes("CURRENCY_PROVIDER", [...]) — codes HTTP_ERROR, PARSE_ERROR, UPSTREAM_ERROR, UNSUPPORTED_BASE, MISSING_CONFIG, UNKNOWN_CURRENCY.
ADDED: CurrencyProviderError extends SuaveplanError<CurrencyProviderErrorCode> carrying optional providerName / status / upstreamMessage discriminants.

Out of scope

Rate-limit-aware RateLimitedProvider wrapper — pending @suaveplan/rate-limiter (exists upstream, not yet migrated to genesis).
Retry + backoff wrapper — pending @suaveplan/retry audit for genesis parity (the upstream is migrated but its integration shape with these providers is a follow-up).
Historical-rate endpoints (fetchHistoricalRates(date)) — additive surface that requires a coordinated CurrencyProvider interface extension in @suaveplan/currency.
WebSocket streaming adapters (Binance / Kraken) — additive surface; spec lives in a separate change.
On-chain oracle adapter (Chainlink / Pyth) — pending @suaveplan/cryptocurrency chain registry.
AggregatorProvider (volume-weighted multi-source average) — depends on the historical-rate surface and rate-limit wrapper.
Provider health-monitor background job — depends on @suaveplan/job-scheduler integration.
OpenTelemetry per-request spans / counters — pending coordinated observability surface in @suaveplan/currency.
Stablecoin redirect routing — additive optimisation, no public-surface change.

Source mapping

This change derives from ../suaveplan/enterprise/currency-providers.md.

Requirement	Source lines	Notes
9 providers (3 fiat + 5 crypto + 1 virtual)	L17-L31	verbatim
`ApiKeyConfig` / `NoKeyConfig` / `HttpFetchOptions`	L17-L19, L30	verbatim
`getCoinGeckoId` helper	L17, L25	verbatim
`VirtualCurrencyProvider` runtime mutators	L29, L70-L86 of upstream `virtual.ts`	verbatim
Test coverage parity for Fixer / OXR / CoinMarketCap	L50-L51	upstream had 6/9 covered; genesis ships 9/9
Typed error hierarchy (replace plain `Error`)	L52-L53	enhanced: `CurrencyProviderError` + 6 codes
Injectable `FetchLike` per provider	L40-L41, L66-L67	enhanced: enables real-fake tests, removes `vi.stubGlobal`
Universal-tier purity	L60-L69	verbatim (genesis cross-cutting baseline)
Subpath exports per provider	upstream `package.json` `exports`	verbatim
Sibling `.md` per file	L61-L63	verbatim (genesis cross-cutting)
100% Istanbul coverage	L61, L101	verbatim (genesis cross-cutting)

Requirements with no source line

Requirement	Justification
Folder-naming rule §10 (`providers/ecb/ecb.ts`)	Genesis-wide structural rule from `openspec/AGENTS.md §10`; upstream used flat `fiat/ecb.ts` / `crypto/binance.ts` which collides once a 10th provider arrives.
`@suaveplan/testing/runner` import for tests	Genesis-wide CI gate from `openspec/AGENTS.md §7` / CLAUDE.md rule 11.
Zero `export *` in feature barrels	Genesis-wide rule §6a / CLAUDE.md rule 10.
`defineCodes` registry under `@suaveplan/error`	Genesis-wide foundation pattern; upstream threw plain `Error`.

Verification approach

Every requirement in the spec delta has a **Verified by:** line naming concrete it(...) titles in these files:

src/providers/ecb/ecb.test.ts — ECB XML parsing, base conversion, filtering, error handling, custom baseUrl, FetchLike injection.
src/providers/fixer/fixer.test.ts — Fixer API call, success-payload handling, error-payload handling, params construction, custom base / targets.
src/providers/open-exchange-rates/open-exchange-rates.test.ts — OXR endpoint construction, targets filtering, timestamp conversion.
src/providers/binance/binance.test.ts — symbol-suffix matching, zero-price skip, target filtering, custom baseUrl.
src/providers/coingecko/coingecko.test.ts — getCoinGeckoId case-insensitivity, ID→symbol mapping, non-USD base.
src/providers/coinmarketcap/coinmarketcap.test.ts — API-key header, quotes parsing, target list construction.
src/providers/cryptocompare/cryptocompare.test.ts — invert-price, zero-price skip, default targets.
src/providers/kraken/kraken.test.ts — pair→symbol reverse mapping, Kraken error array, target filtering.
src/providers/virtual/virtual.test.ts — addCurrency / updateRate / removeCurrency / getCurrencyCodes / getRate, virtual-base conversion.
src/error-codes/error-codes.test.ts — every CURRENCY_PROVIDER.* code reachable; SuaveplanError contract preserved.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/currency-providers to enumerate. This is a brand-new package on genesis, so no current dependents exist:

No dependents (verified by bunx turbo ls --filter=...@suaveplan/currency-providers).

Downstream packages that will consume this once they migrate (@suaveplan/payment, @suaveplan/booking, api-plugin-virtual-currency, etc.) are out of scope here.

Migration impact

New package — additive only. No existing consumers; nothing breaks.

9.0 KiB Raw Permalink Blame History