Initial Commit

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

@@ -0,0 +1,87 @@
+# @suaveplan/currency-provider-kraken - Universal Kraken public-ticker rate provider for @suaveplan/currency. Wraps Kraken's free no-API-key /0/public/Ticker endpoint into a CurrencyProvider with the slim core's shared httpRequest helper, typed CurrencyProviderError (HTTP_ERROR / PARSE_ERROR / UPSTREAM_ERROR / UNKNOWN_CURRENCY), and the 12-symbol BTC/ETH/SOL/USDT/DOT/ADA/LINK/AVAX/ATOM/LTC/DOGE/XRP coverage matched against Kraken's non-standard pair names.
+
+Universal Kraken public-ticker rate provider for `@suaveplan/currency`.
+Wraps Kraken's free, no-API-key `/0/public/Ticker` endpoint into a
+`CurrencyProvider` so a `CurrencyConverter` can price the major crypto
+pairs against USD without callers ever seeing Kraken's non-standard pair
+names (`XXBTZUSD`, `XETHZUSD`, `XDGUSD`, …).
+
+Concrete sibling of the slim `@suaveplan/currency-providers` core — uses
+the shared `httpRequest()` helper, raises the shared `CurrencyProviderError`
+codes (`HTTP_ERROR`, `PARSE_ERROR`, `UPSTREAM_ERROR`, `UNKNOWN_CURRENCY`),
+and accepts the shared `NoKeyConfig` (optional `baseUrl`, optional injectable
+`FetchLike`) plus an optional `extraSymbols` map for caller-supplied
+extensions.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [provider](./src/provider/provider.md) — `KrakenProvider` is the universal `CurrencyProvider` implementation for Kraken's free `/0/public/Ticker` endpoint.…
+  - [provider](./src/provider/provider.md) — `KrakenProvider` is the universal `CurrencyProvider` implementation for Kraken's free `/0/public/Ticker` endpoint.…
+- [symbols](./src/symbols/symbols.md) — The Kraken public ticker addresses pairs by non-standard names — `XXBTZUSD` for BTC/USD, `XETHZUSD` for ETH/USD, `XDGUS…
+  - [symbols](./src/symbols/symbols.md) — The Kraken public ticker addresses pairs by non-standard names — `XXBTZUSD` for BTC/USD, `XETHZUSD` for ETH/USD, `XDGUS…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/currency-provider-kraken @suaveplan/currency @suaveplan/currency-providers
+```
+
+## Quick start
+
+```ts
+import { CurrencyConverter } from "@suaveplan/currency";
+import { KrakenProvider } from "@suaveplan/currency-provider-kraken";
+
+const provider = new KrakenProvider();
+const converter = new CurrencyConverter({ provider });
+
+const btcPerUsd = await converter.getRate("USD", "BTC"); // e.g. 0.0000149
+const ethPerUsd = await converter.getRate("USD", "ETH"); // e.g. 0.0002857
+```
+
+Or register through the slim core's registry:
+
+```ts
+import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
+import { KrakenProvider } from "@suaveplan/currency-provider-kraken";
+
+const registry = new CurrencyProviderRegistry();
+registry.register(new KrakenProvider());
+
+const provider = registry.get("kraken");
+```
+
+## Features
+
+- No API key — Kraken's public endpoint is free (per-IP rate-limited)
+- 12 high-volume symbols out of the box: BTC, ETH, SOL, USDT, DOT, ADA,
+  LINK, AVAX, ATOM, LTC, DOGE, XRP
+- Optional `extraSymbols` for newly-listed pairs without forking
+- Reciprocal-of-USD rate model — `rates[X] = 1 / lastTradeClosedPriceUsd`
+- Single-round-trip batch fetch (Kraken supports a comma-separated `pair=`
+  query)
+- Uses the slim core's `httpRequest()` so HTTP errors, timeouts, and caller
+  `AbortSignal` propagation are uniform across providers
+- Maps wire-level failure modes to typed `CurrencyProviderError`:
+  `HTTP_ERROR`, `UPSTREAM_ERROR`, `PARSE_ERROR`, `UNKNOWN_CURRENCY`
+- Universal — no `node:`/`bun:`/DOM imports; runs unchanged under
+  Node ≥ 18, Bun, modern browsers (subject to Kraken's CORS policy), Web
+  Workers
+
+## Modules
+
+- [`src/provider/provider.md`](./src/provider/provider.md) —
+  `KrakenProvider` class, `KrakenProviderConfig`, `DEFAULT_KRAKEN_BASE_URL`
+- [`src/symbols/symbols.md`](./src/symbols/symbols.md) —
+  `KRAKEN_SYMBOL_MAP`, `KRAKEN_PAIR_TO_SYMBOL`, `mergeSymbolMap`
+
+## Status
+
+`0.1.0` (pre-graduation). native sibling of the slim
+`@suaveplan/currency-providers` core landed by
+the design document. See
+the design proposal for
+the migration parity table and source mapping.
+