67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
# @suaveplan/currency-provider-ecb - Universal @suaveplan/currency provider for the European Central Bank (ECB) daily exchange-rates XML feed. Free, no API key. Implements the slim @suaveplan/currency-providers contract: typed CurrencyProviderError, injectable FetchLike from @suaveplan/types, shared httpRequest helper, mathematical conversion to any non-EUR base, AbortSignal propagation, target filtering, PARSE_ERROR / UNSUPPORTED_BASE / UNKNOWN_CURRENCY / HTTP_ERROR coverage.
|
|
|
|
Universal `@suaveplan/currency` rate provider for the European Central
|
|
Bank's daily exchange-rates XML feed. Free, no API key required. Built on the
|
|
slim `@suaveplan/currency-providers` plugin core: typed
|
|
`CurrencyProviderError` on every failure path, shared `httpRequest()` helper
|
|
for HTTP wrapping + abort-signal composition, injectable `FetchLike` from
|
|
`@suaveplan/types`, mathematical conversion to any non-EUR base, target
|
|
filtering with `UNKNOWN_CURRENCY` guarding, and `PARSE_ERROR` protection
|
|
against silently caching an empty rate map.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [ecb](./src/ecb/ecb.md) — `EcbProvider` is the `@suaveplan/currency` rate-source implementation for the European Central Bank's daily reference-r…
|
|
- [ecb](./src/ecb/ecb.md) — `EcbProvider` is the `@suaveplan/currency` rate-source implementation for the European Central Bank's daily reference-r…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/currency-provider-ecb @suaveplan/currency @suaveplan/currency-providers
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import { CurrencyConverter } from "@suaveplan/currency";
|
|
import { EcbProvider } from "@suaveplan/currency-provider-ecb";
|
|
|
|
const converter = new CurrencyConverter({ provider: new EcbProvider() });
|
|
const rate = await converter.getRate("EUR", "USD");
|
|
```
|
|
|
|
Or via the slim core's registry, alongside other sibling provider packages:
|
|
|
|
```ts
|
|
import { CurrencyConverter } from "@suaveplan/currency";
|
|
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
|
|
import { EcbProvider } from "@suaveplan/currency-provider-ecb";
|
|
|
|
const registry = new CurrencyProviderRegistry();
|
|
registry.register(new EcbProvider());
|
|
|
|
const converter = new CurrencyConverter({ provider: registry.get("ecb") });
|
|
```
|
|
|
|
## Features
|
|
|
|
- Free, no API key.
|
|
- ~30 fiat currencies, EUR-quoted upstream; non-EUR bases derived
|
|
arithmetically.
|
|
- Daily refresh (~16:00 CET); weekends / holidays return the last published
|
|
snapshot.
|
|
- `RateFetchOptions.signal` forwarded through the slim core's HTTP helper.
|
|
- Typed `CurrencyProviderError` codes: `HTTP_ERROR`, `PARSE_ERROR`,
|
|
`UNSUPPORTED_BASE`, `UNKNOWN_CURRENCY`.
|
|
- Universal (browser / Web Worker / Node 18+ / Bun).
|
|
- Zero runtime deps beyond `@suaveplan/currency`,
|
|
`@suaveplan/currency-providers`, `@suaveplan/types`, `tslib`.
|
|
|
|
## Modules
|
|
|
|
- [`src/ecb/ecb.md`](./src/ecb/ecb.md) — `EcbProvider` class, configuration,
|
|
error matrix, advanced examples.
|
|
|