Initial Commit

packages/money/finance/currency-provider-fixer/README.md

@@ -0,0 +1,89 @@
+# @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.
+