Initial Commit
This commit is contained in:
187
openspec/specs/currency-provider-coingecko/spec.md
Normal file
187
openspec/specs/currency-provider-coingecko/spec.md
Normal file
@@ -0,0 +1,187 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec: currency-provider-coingecko
|
||||
|
||||
**Package**: `@suaveplan/currency-provider-coingecko`
|
||||
**Status**: SHIPPED (2026-05-17 — `add-currency-provider-coingecko`)
|
||||
|
||||
> Folded from `openspec/changes/add-currency-provider-coingecko/specs/currency-provider-coingecko/spec.md`
|
||||
> on 2026-05-17.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: CoinGeckoProvider implements the CurrencyProvider contract
|
||||
|
||||
The package SHALL export `CoinGeckoProvider`, a class implementing the
|
||||
`CurrencyProvider` contract from `@suaveplan/currency`. It SHALL expose the
|
||||
static identity fields `name = "coingecko"`, `supportsCrypto = true`, and
|
||||
`supportsFiat = true`. The constructor SHALL accept an optional
|
||||
configuration object of shape `NoKeyConfig & { readonly apiKey?: string }`;
|
||||
omitting the config (free public tier) SHALL be a valid call.
|
||||
|
||||
#### Scenario: provider declares stable metadata at construction
|
||||
|
||||
- **WHEN** a caller instantiates `new CoinGeckoProvider()` with no config
|
||||
- **THEN** the returned instance carries `name === "coingecko"`,
|
||||
`supportsCrypto === true`, and `supportsFiat === true`
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"exposes stable name and supports flags"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: fetchRates uses the shared httpRequest helper with default base URL
|
||||
|
||||
`fetchRates(options?)` SHALL build the request URL from the configured base
|
||||
URL (default `https://api.coingecko.com/api/v3`), append
|
||||
`/simple/price?ids=<curated-ids>&vs_currencies=<base-lower>` query
|
||||
parameters, and issue the request through `httpRequest()` from
|
||||
`@suaveplan/currency-providers`. The injected `FetchLike` from
|
||||
`ProviderConfigBase.fetch` (default `globalThis.fetch`) SHALL be used. The
|
||||
caller's `RateFetchOptions.signal` SHALL be forwarded to `httpRequest` so
|
||||
abort-signal composition propagates.
|
||||
|
||||
#### Scenario: keyless call hits the default endpoint with vs_currencies derived from base
|
||||
|
||||
- **WHEN** `new CoinGeckoProvider().fetchRates({ base: "USD" })` runs with
|
||||
an injected `FetchLike` that records the request URL
|
||||
- **THEN** the recorded URL SHALL begin with
|
||||
`https://api.coingecko.com/api/v3/simple/price?ids=` and SHALL end with
|
||||
`&vs_currencies=usd`
|
||||
|
||||
#### Scenario: custom baseUrl overrides the default
|
||||
|
||||
- **WHEN** `new CoinGeckoProvider({ baseUrl: "https://custom.example/v3",
|
||||
fetch }).fetchRates({ base: "EUR" })` runs
|
||||
- **THEN** the recorded URL SHALL begin with
|
||||
`https://custom.example/v3/simple/price`
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"issues request to default endpoint with vs_currencies from base"` AND `src/coingecko/coingecko.test.ts::"honours custom baseUrl override"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Pro-tier API key is attached as x-cg-pro-api-key header
|
||||
|
||||
When the constructor receives `apiKey`, every outbound request SHALL carry
|
||||
the header `x-cg-pro-api-key: <key>`. When `apiKey` is absent, the
|
||||
provider SHALL NOT attach the header (keeping the request shape
|
||||
indistinguishable from a public-tier call).
|
||||
|
||||
#### Scenario: Pro-tier configuration attaches the header
|
||||
|
||||
- **WHEN** `new CoinGeckoProvider({ apiKey: "secret", fetch }).fetchRates()`
|
||||
runs with a recording `FetchLike`
|
||||
- **THEN** the recorded `init.headers` SHALL contain
|
||||
`"x-cg-pro-api-key": "secret"`
|
||||
|
||||
#### Scenario: free-tier configuration omits the header
|
||||
|
||||
- **WHEN** `new CoinGeckoProvider({ fetch }).fetchRates()` runs with a
|
||||
recording `FetchLike`
|
||||
- **THEN** the recorded `init.headers` SHALL NOT contain a
|
||||
`x-cg-pro-api-key` entry (the entire `headers` field SHALL be absent
|
||||
or empty)
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"attaches x-cg-pro-api-key header when apiKey is provided"` AND `src/coingecko/coingecko.test.ts::"omits x-cg-pro-api-key header when apiKey is absent"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Successful responses invert prices into the converter rate convention
|
||||
|
||||
CoinGecko returns prices as "1 crypto = X fiat"; the package SHALL invert
|
||||
those into "1 base = X crypto" so they match the `RateFetchResult`
|
||||
convention every other provider uses. The result SHALL set `base` to the
|
||||
caller-supplied base (default `"USD"`), `timestamp` to `Date.now()` at
|
||||
parse time, and `rates` to a record keyed by uppercase crypto symbol with
|
||||
inverted numeric values. When `options.targets` is supplied, the result
|
||||
SHALL include only the requested symbols.
|
||||
|
||||
#### Scenario: rates are inverted from upstream price
|
||||
|
||||
- **WHEN** the upstream returns `{ bitcoin: { usd: 67000 }, ethereum: { usd: 3500 } }`
|
||||
and `fetchRates({ base: "USD" })` runs
|
||||
- **THEN** the returned `rates.BTC` SHALL equal `1 / 67000` and
|
||||
`rates.ETH` SHALL equal `1 / 3500`
|
||||
|
||||
#### Scenario: target filtering narrows the result set
|
||||
|
||||
- **WHEN** the upstream returns rates for multiple coins and
|
||||
`fetchRates({ base: "USD", targets: ["BTC", "ETH"] })` runs
|
||||
- **THEN** `Object.keys(result.rates)` SHALL be exactly `["BTC", "ETH"]`
|
||||
(in some order) and SHALL NOT include any other coin
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"inverts upstream prices into base→crypto rates"` AND `src/coingecko/coingecko.test.ts::"filters rates by options.targets"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: HTTP failures raise CurrencyProviderError(HTTP_ERROR)
|
||||
|
||||
Non-2xx responses SHALL surface as
|
||||
`CurrencyProviderError(CURRENCY_PROVIDER_CODES.HTTP_ERROR)` with
|
||||
`providerName === "coingecko"` and `status` populated from the upstream
|
||||
response. The raise SHALL be performed by the shared `httpRequest()` helper
|
||||
(this package does not re-implement the check).
|
||||
|
||||
#### Scenario: 429 from upstream surfaces as HTTP_ERROR with status 429
|
||||
|
||||
- **WHEN** the injected `FetchLike` returns a `Response` with status `429`
|
||||
- **THEN** `fetchRates()` SHALL reject with a `CurrencyProviderError`
|
||||
whose `code === CURRENCY_PROVIDER_CODES.HTTP_ERROR`,
|
||||
`providerName === "coingecko"`, and `status === 429`
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"raises HTTP_ERROR on non-2xx response"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Malformed responses raise PARSE_ERROR or UPSTREAM_ERROR
|
||||
|
||||
When the response body is not valid JSON, `fetchRates()` SHALL raise
|
||||
`CurrencyProviderError(PARSE_ERROR)`. When the body parses as JSON but is
|
||||
not the expected `Record<string, Record<string, number>>` shape (e.g.
|
||||
upstream returns an array or `null` or any non-object), `fetchRates()`
|
||||
SHALL raise `CurrencyProviderError(UPSTREAM_ERROR)`. Both errors SHALL
|
||||
carry `providerName === "coingecko"`.
|
||||
|
||||
#### Scenario: invalid JSON surfaces as PARSE_ERROR
|
||||
|
||||
- **WHEN** the upstream returns a 200 response with body `"not json"`
|
||||
- **THEN** `fetchRates()` SHALL reject with
|
||||
`code === CURRENCY_PROVIDER_CODES.PARSE_ERROR` and
|
||||
`providerName === "coingecko"`
|
||||
|
||||
#### Scenario: wrong-shape JSON surfaces as UPSTREAM_ERROR
|
||||
|
||||
- **WHEN** the upstream returns a 200 response with body `"[]"` (a JSON
|
||||
array — wrong shape)
|
||||
- **THEN** `fetchRates()` SHALL reject with
|
||||
`code === CURRENCY_PROVIDER_CODES.UPSTREAM_ERROR` and
|
||||
`providerName === "coingecko"`
|
||||
|
||||
**Verified by:** `src/coingecko/coingecko.test.ts::"raises PARSE_ERROR when body is not valid JSON"` AND `src/coingecko/coingecko.test.ts::"raises UPSTREAM_ERROR when body is the wrong shape"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: getCoinGeckoId exposes a case-insensitive symbol lookup
|
||||
|
||||
The package SHALL export `getCoinGeckoId(symbol: string)` returning the
|
||||
CoinGecko ID for the curated symbol set (BTC, ETH, SOL, USDT, USDC, BNB,
|
||||
XRP, ADA, DOGE, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC). The lookup
|
||||
SHALL be case-insensitive and SHALL return `undefined` for unknown
|
||||
symbols. When `fetchRates()` receives `options.targets` containing a
|
||||
symbol with no mapping, it SHALL raise
|
||||
`CurrencyProviderError(UNKNOWN_CURRENCY)` proactively (before issuing
|
||||
the HTTP request) carrying the offending symbol in the message.
|
||||
|
||||
#### Scenario: known symbol resolves regardless of case
|
||||
|
||||
- **WHEN** `getCoinGeckoId("btc")` and `getCoinGeckoId("BTC")` are called
|
||||
- **THEN** both SHALL return `"bitcoin"`
|
||||
|
||||
#### Scenario: unknown target raises UNKNOWN_CURRENCY before any HTTP call
|
||||
|
||||
- **WHEN** `fetchRates({ targets: ["BTC", "ZZZ"] })` runs with a
|
||||
recording `FetchLike`
|
||||
- **THEN** the call SHALL reject with
|
||||
`code === CURRENCY_PROVIDER_CODES.UNKNOWN_CURRENCY` AND the recording
|
||||
`FetchLike` SHALL NOT have been invoked
|
||||
|
||||
**Verified by:** `src/coin-ids/coin-ids.test.ts::"returns the CoinGecko id for known symbols regardless of case"` AND `src/coin-ids/coin-ids.test.ts::"returns undefined for unknown symbols"` AND `src/coingecko/coingecko.test.ts::"raises UNKNOWN_CURRENCY when a target has no CoinGecko mapping"`
|
||||
Reference in New Issue
Block a user