Initial Commit

2026-05-27 23:47:53 +01:00
parent fbc70f96e6
commit 9b28db724f
18103 changed files with 1600554 additions and 0 deletions
--- a/packages/money/finance/currency-provider-open-exchange-rates/README.md
+++ b/packages/money/finance/currency-provider-open-exchange-rates/README.md
@@ -0,0 +1,67 @@
+# @suaveplan/currency-provider-open-exchange-rates - Universal @suaveplan/currency provider for openexchangerates.org. API-key (app_id) required. Free tier limited to USD base; paid tiers opt in via allowNonUsdBase. Routes every request through @suaveplan/currency-providers httpRequest() and raises typed CurrencyProviderError for HTTP / parse / upstream / config / base / currency failures.
+
+Universal `@suaveplan/currency` provider for
+[openexchangerates.org](https://openexchangerates.org). Routes `/latest.json`
+through the slim-core `httpRequest()` helper, validates the upstream payload,
+and raises typed `CurrencyProviderError` for every failure mode.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [provider](./src/provider/provider.md) — `OpenExchangeRatesProvider` is the `@suaveplan/currency` provider for openexchangerates.org. It wraps the `/latest.json…
+  - [provider](./src/provider/provider.md) — `OpenExchangeRatesProvider` is the `@suaveplan/currency` provider for openexchangerates.org. It wraps the `/latest.json…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/currency-provider-open-exchange-rates
+```
+
+## Quick start
+
+```ts
+import { CurrencyConverter } from "@suaveplan/currency";
+import { OpenExchangeRatesProvider } from "@suaveplan/currency-provider-open-exchange-rates";
+
+const oxr = new OpenExchangeRatesProvider({
+    apiKey: process.env.OXR_APP_ID!,
+    // allowNonUsdBase: true,  // paid plans only
+});
+
+const converter = new CurrencyConverter({ provider: oxr });
+
+const usdToEur = await converter.getRate({ from: "USD", to: "EUR" });
+console.log(usdToEur);
+```
+
+## Configuration
+
+| Field             | Type        | Default                                 | Notes                                                            |
+| ----------------- | ----------- | --------------------------------------- | ---------------------------------------------------------------- |
+| `apiKey`          | `string`    | —                                       | OXR `app_id`. Empty string raises `MISSING_CONFIG`.              |
+| `baseUrl`         | `string?`   | `https://openexchangerates.org/api`     | Override for staging / proxy fixtures.                           |
+| `fetch`           | `FetchLike?`| `globalThis.fetch`                      | Injectable for testing.                                          |
+| `allowNonUsdBase` | `boolean?`  | `false`                                 | Set `true` on paid plans to forward non-USD `base` requests.     |
+
+## Error codes
+
+Every failure mode raises `CurrencyProviderError` from
+`@suaveplan/currency-providers` with one of:
+
+- `CURRENCY_PROVIDER.MISSING_CONFIG` — empty `apiKey`.
+- `CURRENCY_PROVIDER.UNSUPPORTED_BASE` — non-USD base on free tier.
+- `CURRENCY_PROVIDER.HTTP_ERROR` — non-2xx response (raised by `httpRequest()`).
+- `CURRENCY_PROVIDER.PARSE_ERROR` — body is not JSON or missing required fields.
+- `CURRENCY_PROVIDER.UPSTREAM_ERROR` — 2xx with OXR `{ error: true, … }` body.
+- `CURRENCY_PROVIDER.UNKNOWN_CURRENCY` — `options.targets` contains a code absent from the upstream rates map.
+
+## Modules
+
+- [`src/provider/provider.md`](./src/provider/provider.md) — `OpenExchangeRatesProvider` class and config.
+
+## Tier
+
+Universal — runs in Node 18+, Bun, browsers, and Web Workers without any
+runtime polyfill.
+