first commit

docs/money/finance/currency-provider-cryptocompare/README.md

@@ -0,0 +1,75 @@
+# @suaveplan/currency-provider-cryptocompare - Universal CryptoCompare crypto-rates provider for @suaveplan/currency. Sibling provider package on the slim @suaveplan/currency-providers core (httpRequest, defineCurrencyProvider, CurrencyProviderError, NoKeyConfig). Optional API key — free tier works keyless; key boosts the rate limit and is sent via `authorization: Apikey <key>` header.
+
+Universal CryptoCompare crypto-rates provider for `@suaveplan/currency`.
+Sibling provider package on top of the slim `@suaveplan/currency-providers`
+core (`httpRequest`, `CurrencyProviderError`, `NoKeyConfig`). Optional API
+key — CryptoCompare's free tier works fully keyless; supplying a key boosts
+the upstream rate limit and is sent on every request via the
+`authorization: Apikey <key>` header.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [cryptocompare](./src/cryptocompare/cryptocompare.md) — `CryptoCompareProvider` implements the `CurrencyProvider` contract from `@suaveplan/currency` on top of CryptoCompare's…
+  - [cryptocompare](./src/cryptocompare/cryptocompare.md) — `CryptoCompareProvider` implements the `CurrencyProvider` contract from `@suaveplan/currency` on top of CryptoCompare's…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/currency-provider-cryptocompare \
+       @suaveplan/currency \
+       @suaveplan/currency-providers
+```
+
+## Quick start
+
+```ts
+import { CurrencyConverter } from "@suaveplan/currency";
+import { CryptoCompareProvider } from "@suaveplan/currency-provider-cryptocompare";
+
+const provider = new CryptoCompareProvider({
+    apiKey: process.env.CRYPTOCOMPARE_API_KEY, // optional
+});
+
+const converter = new CurrencyConverter({
+    provider,
+    staleDurationMs: 60_000,
+});
+
+const conversion = await converter.convert(amount, "BTC");
+```
+
+Or register through the slim-core registry:
+
+```ts
+import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
+import { CryptoCompareProvider } from "@suaveplan/currency-provider-cryptocompare";
+
+const registry = new CurrencyProviderRegistry();
+registry.register(new CryptoCompareProvider());
+const provider = registry.get("cryptocompare");
+```
+
+## Modules
+
+- [`cryptocompare/cryptocompare`](./src/cryptocompare/cryptocompare.md) —
+  `CryptoCompareProvider` class, `CryptoCompareConfig` interface, error
+  mapping for `HTTP_ERROR` / `PARSE_ERROR` / `UPSTREAM_ERROR` /
+  `UNKNOWN_CURRENCY`.
+
+## Errors
+
+Every failure path raises `CurrencyProviderError` from the slim core:
+
+| Code | Raised when |
+|---|---|
+| `CURRENCY_PROVIDER.HTTP_ERROR` | Non-2xx HTTP response (shared `httpRequest`) |
+| `CURRENCY_PROVIDER.PARSE_ERROR` | Body not valid JSON, or payload not a JSON object |
+| `CURRENCY_PROVIDER.UPSTREAM_ERROR` | Payload carries `Response: "Error"` |
+| `CURRENCY_PROVIDER.UNKNOWN_CURRENCY` | No requested symbol produced a finite positive quote |
+
+Dispatch on `error.code`, not the message string. The instance also
+carries `providerName: "cryptocompare"`, optional `status` (for HTTP_ERROR),
+and optional `upstreamMessage` (for UPSTREAM_ERROR).
+