@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 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).

Documentation tree

fixer — FixerProvider is the Fixer.io sibling provider for the slim @suaveplan/currency-providers core. It implements the `…
- fixer — FixerProvider is the Fixer.io sibling provider for the slim @suaveplan/currency-providers core. It implements the `…

Install

bun add @suaveplan/currency-provider-fixer \
        @suaveplan/currency-providers \
        @suaveplan/currency

Quick start

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:

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 — 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.

3.5 KiB Raw Blame History