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