68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
# @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.
|
|
|