# @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](https://openexchangerates.org). Routes `/latest.json`
through the slim-core `httpRequest()` helper, validates the upstream payload,
and raises typed `CurrencyProviderError` for every failure mode.

<!-- begin:auto-docs -->
## Documentation tree

- [provider](./src/provider/provider.md) — `OpenExchangeRatesProvider` is the `@suaveplan/currency` provider for openexchangerates.org. It wraps the `/latest.json…
  - [provider](./src/provider/provider.md) — `OpenExchangeRatesProvider` is the `@suaveplan/currency` provider for openexchangerates.org. It wraps the `/latest.json…
<!-- end:auto-docs -->

## Install

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

## Quick start

```ts
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`](./src/provider/provider.md) — `OpenExchangeRatesProvider` class and config.

## Tier

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