@suaveplan/currency-provider-open-exchange-rates - Universal @suaveplan/currency provider for openexchangerates.org. API-key (app_id) required. Free tier limited to USD base; paid tiers opt in via allowNonUsdBase. Routes every request through @suaveplan/currency-providers httpRequest() and raises typed CurrencyProviderError for HTTP / parse / upstream / config / base / currency failures.

Universal @suaveplan/currency provider for openexchangerates.org. Routes /latest.json through the slim-core httpRequest() helper, validates the upstream payload, and raises typed CurrencyProviderError for every failure mode.

Documentation tree

provider — OpenExchangeRatesProvider is the @suaveplan/currency provider for openexchangerates.org. It wraps the `/latest.json…
- provider — OpenExchangeRatesProvider is the @suaveplan/currency provider for openexchangerates.org. It wraps the `/latest.json…

Install

bun add @suaveplan/currency-provider-open-exchange-rates

Quick start

import { CurrencyConverter } from "@suaveplan/currency";
import { OpenExchangeRatesProvider } from "@suaveplan/currency-provider-open-exchange-rates";

const oxr = new OpenExchangeRatesProvider({
    apiKey: process.env.OXR_APP_ID!,
    // allowNonUsdBase: true,  // paid plans only
});

const converter = new CurrencyConverter({ provider: oxr });

const usdToEur = await converter.getRate({ from: "USD", to: "EUR" });
console.log(usdToEur);

Configuration

Field	Type	Default	Notes
`apiKey`	`string`	—	OXR `app_id`. Empty string raises `MISSING_CONFIG`.
`baseUrl`	`string?`	`https://openexchangerates.org/api`	Override for staging / proxy fixtures.
`fetch`	`FetchLike?`	`globalThis.fetch`	Injectable for testing.
`allowNonUsdBase`	`boolean?`	`false`	Set `true` on paid plans to forward non-USD `base` requests.

Error codes

Every failure mode raises CurrencyProviderError from @suaveplan/currency-providers with one of:

CURRENCY_PROVIDER.MISSING_CONFIG — empty apiKey.
CURRENCY_PROVIDER.UNSUPPORTED_BASE — non-USD base on free tier.
CURRENCY_PROVIDER.HTTP_ERROR — non-2xx response (raised by httpRequest()).
CURRENCY_PROVIDER.PARSE_ERROR — body is not JSON or missing required fields.
CURRENCY_PROVIDER.UPSTREAM_ERROR — 2xx with OXR { error: true, … } body.
CURRENCY_PROVIDER.UNKNOWN_CURRENCY — options.targets contains a code absent from the upstream rates map.

Modules

src/provider/provider.md — OpenExchangeRatesProvider class and config.

Tier

Universal — runs in Node 18+, Bun, browsers, and Web Workers without any runtime polyfill.

3.3 KiB Raw Blame History