first commit

docs/money/finance/currency-provider-coingecko/src/coin-ids/coin-ids.md

@@ -0,0 +1,88 @@
+# coin-ids
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the curated mapping from uppercase ticker symbol (`BTC`, `ETH`, …) to
+the opaque CoinGecko coin id (`bitcoin`, `ethereum`, …) that the
+`/simple/price` endpoint requires. Without this translation step the
+provider would have to either fall back to CoinGecko's heavyweight
+`/coins/list` discovery endpoint (~10k entries, defeats tree-shaking) or
+ask every caller to learn CoinGecko's id convention — neither is
+acceptable for a slim sibling.
+
+## Features
+
+- Frozen `COIN_IDS` map covering the top 16 cryptos by market cap at
+  landing (BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT, AVAX,
+  MATIC, LINK, UNI, ATOM, LTC).
+- Case-insensitive `getCoinGeckoId(symbol)` lookup returning `string | undefined`.
+- Zero runtime dependencies; pure data + a one-line lookup function.
+
+## Usage: Basic
+
+```ts
+import { getCoinGeckoId } from "@suaveplan/currency-provider-coingecko/coin-ids/coin-ids";
+
+getCoinGeckoId("BTC"); // "bitcoin"
+getCoinGeckoId("eth"); // "ethereum" — case-insensitive
+getCoinGeckoId("ZZZ"); // undefined — unknown symbol
+```
+
+## Usage: Advanced
+
+The provider uses `getCoinGeckoId` as the proactive `UNKNOWN_CURRENCY`
+gate. Consumers can mirror the same pattern when composing their own
+filters before hitting the registry:
+
+```ts
+import {
+ COIN_IDS,
+ getCoinGeckoId,
+} from "@suaveplan/currency-provider-coingecko/coin-ids/coin-ids";
+
+function partitionSupported(symbols: readonly string[]): {
+ supported: string[];
+ unknown: string[];
+} {
+ const supported: string[] = [];
+ const unknown: string[] = [];
+ for (const symbol of symbols) {
+  if (getCoinGeckoId(symbol) !== undefined) {
+   supported.push(symbol);
+  } else {
+   unknown.push(symbol);
+  }
+ }
+ return { supported, unknown };
+}
+
+// Iterate the full map when generating a UI dropdown:
+const everyKnown = Object.keys(COIN_IDS);
+```
+
+## API Reference
+
+### `COIN_IDS: Readonly<Record<string, string>>`
+
+Frozen mapping from uppercase ticker (key) to CoinGecko coin id (value).
+Keys are always uppercase; mutation throws because the object is frozen.
+
+### `getCoinGeckoId(symbol: string): string | undefined`
+
+Returns the CoinGecko coin id for the given symbol. The input is
+upper-cased before the lookup, so `"btc"` and `"BTC"` both resolve to
+`"bitcoin"`. Returns `undefined` for any symbol not present in
+`COIN_IDS`. Does not throw.
+
+## Implementation Notes
+
+The map is intentionally hand-curated rather than fetched at runtime: a
+sibling that issues a discovery call before every batch would (a) add a
+network round trip every consumer pays for once, (b) bloat the
+in-memory cache, and (c) couple this package's reliability to a second
+upstream endpoint whose response shape can drift. Adding a new symbol is
+a one-line PR; the trade-off is heavily skewed toward "type it in".