90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# @suaveplan/currency-provider-fixer - Fixer.io fiat-rates CurrencyProvider sibling of @suaveplan/currency-providers. API-key required; 170+ fiat currencies; maps upstream error codes (105 → UNSUPPORTED_BASE, 201/202 → UNKNOWN_CURRENCY, other success:false → UPSTREAM_ERROR) to the slim core's typed CurrencyProviderError. Universal, FetchLike-injectable.
|
|
|
|
[Fixer.io](https://fixer.io/) fiat-rates sibling provider for the slim
|
|
`@suaveplan/currency-providers` core. Implements the `CurrencyProvider`
|
|
contract from `@suaveplan/currency`, requires an API key, and maps the
|
|
upstream `{ success, error: { code, info } }` envelope to typed
|
|
`CurrencyProviderError` codes — including the free-tier
|
|
`base_currency_access_restricted` case (`UNSUPPORTED_BASE`).
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [fixer](./src/fixer/fixer.md) — `FixerProvider` is the Fixer.io sibling provider for the slim `@suaveplan/currency-providers` core. It implements the `…
|
|
- [fixer](./src/fixer/fixer.md) — `FixerProvider` is the Fixer.io sibling provider for the slim `@suaveplan/currency-providers` core. It implements the `…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/currency-provider-fixer \
|
|
@suaveplan/currency-providers \
|
|
@suaveplan/currency
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import { CurrencyConverter } from "@suaveplan/currency";
|
|
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
|
|
import { FixerProvider } from "@suaveplan/currency-provider-fixer";
|
|
|
|
const registry = new CurrencyProviderRegistry();
|
|
registry.register(new FixerProvider({ apiKey: process.env.FIXER_KEY! }));
|
|
|
|
const converter = new CurrencyConverter({
|
|
provider: registry.get("fixer"),
|
|
staleDurationMs: 3_600_000,
|
|
});
|
|
|
|
const rate = await converter.getRate("EUR", "GBP");
|
|
```
|
|
|
|
Direct instantiation without the registry is equally supported:
|
|
|
|
```ts
|
|
const provider = new FixerProvider({ apiKey: process.env.FIXER_KEY! });
|
|
const result = await provider.fetchRates();
|
|
```
|
|
|
|
## Features
|
|
|
|
- Implements `CurrencyProvider` (`name = "fixer"`, `supportsFiat = true`,
|
|
`supportsCrypto = false`).
|
|
- Constructor takes the slim core's shared `ApiKeyConfig`; an empty
|
|
`apiKey` raises `CURRENCY_PROVIDER.MISSING_CONFIG` synchronously
|
|
before any network call (no wasted quota).
|
|
- HTTP transport via the slim core's `httpRequest` — `AbortSignal`
|
|
composition, non-2xx → typed `HTTP_ERROR`, `providerName` / `status`
|
|
populated on the raised error.
|
|
- Typed upstream-code mapping: `105` → `UNSUPPORTED_BASE`, `201` / `202`
|
|
→ `UNKNOWN_CURRENCY`, any other `success: false` → `UPSTREAM_ERROR`
|
|
with `upstreamMessage` carrying the upstream `error.info`.
|
|
- `PARSE_ERROR` for malformed JSON, non-object JSON, and successful
|
|
envelopes missing required fields.
|
|
- Universal — runs unchanged under Node 18+, Bun, modern browsers,
|
|
and Web Workers.
|
|
- One subpath export, one feature module; explicit named barrels;
|
|
100/100/100/100 istanbul coverage.
|
|
|
|
## Modules
|
|
|
|
- [`src/fixer/fixer.md`](./src/fixer/fixer.md) — `FixerProvider` class,
|
|
envelope handling, error-code mapping table.
|
|
|
|
## Sibling packages
|
|
|
|
Part of the foundation-with-sibling-plugins family established by
|
|
the design document. Other concrete
|
|
providers (ECB, Open Exchange Rates, Binance, CoinGecko, CoinMarketCap,
|
|
CryptoCompare, Kraken, Virtual) ship as separate
|
|
`@suaveplan/currency-provider-<name>` packages.
|
|
|
|
## Status
|
|
|
|
`0.1.0` (pre-graduation). New native sibling landed on
|
|
2026-05-17 against the slimmed core. See
|
|
the design proposal
|
|
for the proposal, design, and parity checklist.
|
|
|