suaveplan/openspec/archive/2026-05-17-add-currency-provider-open-exchange-rates/proposal.md

Add @suaveplan/currency-provider-open-exchange-rates

Package: @suaveplan/currency-provider-open-exchange-rates Status: PROPOSED Type: new-package

• Spec delta: ./specs/currency-provider-open-exchange-rates/spec.md

Why

The 2026-05-17 slim of @suaveplan/currency-providers removed the nine bundled provider implementations and committed to landing each as an independent sibling package on the foundation-with-sibling-plugins shape established by @suaveplan/network-plugin-* and @suaveplan/drive-plugin-*. This change lands the Open Exchange Rates (OXR) provider so consumers that only need OXR install one small package instead of the bundled umbrella, and OXR can iterate on its own version cadence when the upstream API changes (free-plan base-only, historical endpoints, currency-list updates).

What changes

• ADDED: OpenExchangeRatesProvider — class implementing CurrencyProvider from @suaveplan/currency; consumes httpRequest() from @suaveplan/currency-providers; raises CurrencyProviderError with codes HTTP_ERROR, PARSE_ERROR, UPSTREAM_ERROR, MISSING_CONFIG, UNSUPPORTED_BASE, UNKNOWN_CURRENCY.
• ADDED: subpath export ./provider/provider for tree-shakeable import.
• ADDED: package root barrel re-exporting OpenExchangeRatesProvider and the type alias OpenExchangeRatesProviderConfig (= ApiKeyConfig from @suaveplan/currency-providers).

Out of scope

• Historical-rate endpoint (/historical/<date>.json) — deferred to a follow-up change. The upstream slim refactor's ## Out of scope block explicitly defers historical rates for every provider in the wave; this package keeps parity with that boundary.
• Retry / backoff / rate-limit-header surfacing / OTel — deferred to the same cross-cutting follow-up that the slim core deferred them to.
• The five other OXR endpoints (/currencies.json, /usage.json, /convert/{value}/{from}/{to}, /ohlc.json, /time-series.json) — the CurrencyProvider contract only exposes bulk-fetch via /latest.json; the rest are out of contract.

Source mapping

This change derives from ../suaveplan/enterprise/currency-providers.md and the upstream OXR implementation at ../suaveplan/packages/finance/currency-providers/src/fiat/open-exchange-rates.ts.

Requirement	Source lines	Notes
OXR-001 implements CurrencyProvider with supportsFiat=true, supportsCrypto=false, name="open-exchange-rates"	open-exchange-rates.ts L15-L19	verbatim, plus tier purity (no Node-only APIs)
OXR-002 fetches /latest.json?app_id=<key>&base=<base> via httpRequest()	open-exchange-rates.ts L28-L37	reworded — upstream called fetch() directly; genesis routes through slim-core httpRequest() per slim spec
OXR-003 maps response { base, rates, timestamp } to RateFetchResult with timestamp * 1000 to convert OXR's Unix seconds to ms	open-exchange-rates.ts L39-L43, L56-L60	verbatim
OXR-004 honours RateFetchOptions.targets by filtering rates map	open-exchange-rates.ts L46-L54	verbatim
OXR-005 free-tier limits base to USD; explicit non-USD base raises UNSUPPORTED_BASE	enterprise audit L12, OXR.md L11-L13, L41-L43	extended — upstream silently let upstream API reject; genesis pre-rejects with a stable error code (the UNSUPPORTED_BASE code is already registered in slim core)

Requirements with no source line

Requirement	Justification
OXR-006 raises MISSING_CONFIG on empty apiKey	MISSING_CONFIG code exists in slim-core registry per archived slim spec; surfacing it from constructor is the genesis baseline for all api-key providers
OXR-007 raises PARSE_ERROR when upstream payload is not the expected shape	Defensive validation — upstream library threw a generic JSON-parse error; genesis maps to typed PARSE_ERROR
OXR-008 raises UPSTREAM_ERROR when upstream returns 2xx with error: true body	OXR documented error/status/message payload shape; upstream library missed it. Genesis surfaces typed UPSTREAM_ERROR with upstreamMessage populated
OXR-009 raises UNKNOWN_CURRENCY when options.targets requests a code not in upstream response	UNKNOWN_CURRENCY code exists in slim-core registry; surfacing it instead of silently dropping the target gives callers a typed handle
OXR-010 honours RateFetchOptions.signal for cancellation	Universal-tier abort propagation — upstream did not honour signal at all; genesis composes via httpRequest() which forwards to the injected fetch
OXR-011 universal-tier purity — no Node APIs, no DOM APIs	Genesis-wide tier policy
OXR-012 100% test coverage, sibling .md on every implementation file	Genesis-wide quality policy

Verification approach

Every requirement carries a **Verified by:** line in the spec delta pointing at concrete it(...) titles. The test surface is:

• src/provider/provider.test.ts — covers OXR-001 through OXR-011 with injected FetchLike recording calls and returning canned responses.
• tests/dep-graph.test.ts — pins dependency invariants (only consumes @suaveplan/currency, @suaveplan/currency-providers, @suaveplan/error, @suaveplan/types).

Migration impact

None — additive only. No current consumers reference this package; the slim core's ## Affected dependents block listed this package as one of nine sibling consumers that would land in the follow-up wave.