Initial Commit

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

@@ -0,0 +1,79 @@
+# @suaveplan/currency-provider-coingecko - Universal CoinGecko sibling for @suaveplan/currency-providers. Exposes CoinGeckoProvider (free public tier + optional Pro-tier x-cg-pro-api-key) and the getCoinGeckoId symbol lookup; routes every request through the shared httpRequest helper and raises typed CurrencyProviderError on HTTP_ERROR / PARSE_ERROR / UPSTREAM_ERROR / UNKNOWN_CURRENCY.
+
+Universal CoinGecko sibling for
+[`@suaveplan/currency-providers`](../currency-providers/README.md). Implements
+the `CurrencyProvider` contract from `@suaveplan/currency` against the
+public `/simple/price` endpoint, with optional Pro-tier `apiKey` support
+attached as `x-cg-pro-api-key` on every outbound request. Both free and
+Pro tiers share the same URL shape, so upgrading is a single-field
+config change.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [coin-ids](./src/coin-ids/coin-ids.md) — Owns the curated mapping from uppercase ticker symbol (`BTC`, `ETH`, …) to the opaque CoinGecko coin id (`bitcoin`, `et…
+  - [coin-ids](./src/coin-ids/coin-ids.md) — Owns the curated mapping from uppercase ticker symbol (`BTC`, `ETH`, …) to the opaque CoinGecko coin id (`bitcoin`, `et…
+- [coingecko](./src/coingecko/coingecko.md) — CoinGecko sibling for `@suaveplan/currency-providers`. Implements the `CurrencyProvider` contract from `@suaveplan/curr…
+  - [coingecko](./src/coingecko/coingecko.md) — CoinGecko sibling for `@suaveplan/currency-providers`. Implements the `CurrencyProvider` contract from `@suaveplan/curr…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/currency-provider-coingecko
+```
+
+## Quick start
+
+```ts
+import { CurrencyConverter } from "@suaveplan/currency";
+import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
+import { CoinGeckoProvider } from "@suaveplan/currency-provider-coingecko";
+
+// Free public tier — no API key required.
+const free = new CoinGeckoProvider();
+
+// Pro tier — pass apiKey; the same provider attaches x-cg-pro-api-key.
+const pro = new CoinGeckoProvider({
+ apiKey: process.env.COINGECKO_PRO_KEY,
+ baseUrl: "https://pro-api.coingecko.com/api/v3",
+});
+
+const registry = new CurrencyProviderRegistry();
+registry.register(pro);
+
+const converter = new CurrencyConverter({
+ provider: registry.get("coingecko"),
+ staleDurationMs: 60_000,
+});
+
+const rates = await registry
+ .get("coingecko")
+ .fetchRates({ base: "USD", targets: ["BTC", "ETH"] });
+```
+
+## Features
+
+- `CoinGeckoProvider implements CurrencyProvider` — drops directly into
+  any `@suaveplan/currency` converter or `CurrencyProviderRegistry`.
+- Truly optional `apiKey` — free tier requires no config; Pro tier
+  attaches `x-cg-pro-api-key` automatically.
+- 16 curated cryptocurrencies (BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA,
+  DOGE, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC).
+- Routes every request through the shared `httpRequest()` helper from
+  `@suaveplan/currency-providers` for abort-signal composition,
+  per-call timeouts, and typed HTTP failures.
+- Proactive `UNKNOWN_CURRENCY` gate — unknown `options.targets` reject
+  before the HTTP call is issued.
+- Typed `CurrencyProviderError` on every failure path: `HTTP_ERROR`,
+  `PARSE_ERROR`, `UPSTREAM_ERROR`, `UNKNOWN_CURRENCY`.
+- Universal — zero browser / Node-only APIs. Works in Node 18+, Bun,
+  modern browsers, and Web Workers.
+
+## Modules
+
+- [`src/coingecko/coingecko.md`](./src/coingecko/coingecko.md) —
+  `CoinGeckoProvider` class + `CoinGeckoConfig` type.
+- [`src/coin-ids/coin-ids.md`](./src/coin-ids/coin-ids.md) — `COIN_IDS`
+  curated map + `getCoinGeckoId(symbol)` lookup.
+