147 lines
7.5 KiB
Markdown
147 lines
7.5 KiB
Markdown
# Add @suaveplan/currency-provider-binance — Binance public-ticker provider
|
|
|
|
**Package**: `@suaveplan/currency-provider-binance`
|
|
**Status**: ARCHIVED
|
|
**Type**: feature (sibling provider in the slim currency-providers wave)
|
|
|
|
- **Design**: ./design.md
|
|
- **Spec delta**: ./specs/currency-provider-binance/spec.md
|
|
|
|
## Why
|
|
|
|
The 2026-05-17 slim refactor of `@suaveplan/currency-providers` removed
|
|
nine concrete provider classes from the umbrella package and committed
|
|
to landing each as its own `@suaveplan/currency-provider-<name>`
|
|
sibling. `BinanceProvider` is the Binance leg of that wave. It is the
|
|
key-less crypto-rates provider in the line-up — alongside CoinGecko,
|
|
CryptoCompare, and Kraken — and the only one that ships sub-second
|
|
trading-desk pricing. Without it the slim core has no working crypto
|
|
provider out of the box; downstream agents would have to hand-roll one,
|
|
which is exactly the bug the slim refactor exists to fix.
|
|
|
|
This change ports the Binance implementation that previously lived at
|
|
`packages/finance/currency-providers/src/crypto/binance.ts` upstream
|
|
into the genesis monorepo as a standalone package, with three quality
|
|
improvements over the upstream form:
|
|
|
|
1. HTTP transport is delegated to the slim core's `httpRequest` helper,
|
|
so `HTTP_ERROR` carries the typed `CurrencyProviderError` shape
|
|
instead of a plain `Error` and abort/timeout composition is uniform
|
|
across every sibling.
|
|
2. Failure paths are split into the four typed codes the slim spec
|
|
defines (`HTTP_ERROR`, `PARSE_ERROR`, `UPSTREAM_ERROR`,
|
|
`UNKNOWN_CURRENCY`) — the upstream form raised a single plain
|
|
`Error` on the HTTP path and silently dropped malformed payloads or
|
|
missing targets.
|
|
3. Payload shape is structurally validated (array of
|
|
`{ symbol: string; price: string }`); upstream took the wire shape
|
|
on faith and would `TypeError` on a Cloudflare error page.
|
|
|
|
## What changes
|
|
|
|
### ADDED
|
|
|
|
- `BinanceProvider` — class implementing the `CurrencyProvider`
|
|
contract on top of the Binance public spot ticker (`GET
|
|
/api/v3/ticker/price`).
|
|
- `BINANCE_PROVIDER_NAME` (`"binance"`) and `BINANCE_DEFAULT_BASE_URL`
|
|
(`"https://api.binance.com/api/v3"`) constants so consumers can wire
|
|
the registry and overrides without string literals.
|
|
|
|
### NOT INCLUDED (out of scope — same deferrals as the slim core)
|
|
|
|
- WebSocket streaming (Binance `/ws/!ticker@arr`) — REST-only for v1
|
|
- Historical klines / candlesticks
|
|
- Authenticated endpoints (account, orders) — non-goal for a
|
|
`CurrencyProvider`
|
|
- Per-call rate-limit accounting — deferred to the future
|
|
`RateLimitedProvider` wrapper from the slim core
|
|
|
|
## Source mapping
|
|
|
|
| Module | Upstream source |
|
|
|---|---|
|
|
| `BinanceProvider` | `../suaveplan/packages/finance/currency-providers/src/crypto/binance.ts` |
|
|
| Sibling-shape contract | `openspec/archive/2026-05-17-slim-currency-providers/design.md` |
|
|
| Slim core surface consumed | `packages/finance/currency-providers/src/{http,error-codes,types}/` |
|
|
|
|
The new genesis-original wrappers (`httpRequest` delegation, typed
|
|
`PARSE_ERROR` / `UPSTREAM_ERROR` / `UNKNOWN_CURRENCY` paths, structural
|
|
payload validation) are listed in the design rationale; they have no
|
|
upstream analogue because upstream raised plain `Error` and ignored
|
|
payload shape.
|
|
|
|
## Parity Checklist
|
|
|
|
| Capability | Upstream | Migrated | Notes |
|
|
|---|---|---|---|
|
|
| Class-based `BinanceProvider implements CurrencyProvider` | ✅ | ✅ | Identical constructor shape; takes `NoKeyConfig` now (super-set of upstream's optional `{ baseUrl }`). |
|
|
| `name === "binance"`, `supportsCrypto === true`, `supportsFiat === false` | ✅ | ✅ | Verbatim. Exposed as `BINANCE_PROVIDER_NAME` for registry wiring. |
|
|
| Default base URL `https://api.binance.com/api/v3` | ✅ | ✅ | Exported as `BINANCE_DEFAULT_BASE_URL` constant. |
|
|
| Custom `baseUrl` override | ✅ | ✅ | Via `NoKeyConfig.baseUrl`. |
|
|
| `GET /ticker/price` fetch | ✅ | ✅ | Now via slim-core `httpRequest`. |
|
|
| Default base `USDT` | ✅ | ✅ | Verbatim. |
|
|
| Suffix-match decoding (`BTCUSDT` → `BTC` when base is `USDT`) | ✅ | ✅ | Plus a defensive length check that rejects symbols equal to the suffix. |
|
|
| Skip zero-price tickers | ✅ | ✅ | Verbatim. |
|
|
| Skip negative-price / non-finite tickers | 🚫 | ⬆️ | Upstream only checked `price > 0` — fails open on `NaN`. Genesis form adds `Number.isFinite`. |
|
|
| Optional `targets` filter | ✅ | ⬆️ | Upstream silently dropped missing targets; genesis raises `UNKNOWN_CURRENCY` so consumers learn about upstream listing changes immediately. |
|
|
| Plain `Error` on non-2xx HTTP | ✅ | 🚫 | Replaced by typed `CurrencyProviderError(HTTP_ERROR)` raised by the slim core's `httpRequest`. Reason: the slim core's contract requires typed errors from every sibling. |
|
|
| Structural payload validation | 🚫 | ⬆️ | Upstream cast the response shape without checking; genesis raises `UPSTREAM_ERROR` on malformed rows. |
|
|
| `PARSE_ERROR` on non-JSON body | 🚫 | ⬆️ | Upstream would leak a runtime `SyntaxError`; genesis wraps `response.json()` in a typed catch. |
|
|
| Injectable `FetchLike` | 🚫 | ⬆️ | Upstream used `globalThis.fetch` directly; genesis form takes a `NoKeyConfig.fetch` override for tests / proxies / edge runtimes. |
|
|
| Optional per-request timeout | 🚫 | ⬆️ | New: `timeoutMs` flows through to `httpRequest` and composes with the caller's `signal`. |
|
|
| `AbortSignal` propagation from `RateFetchOptions` | 🚫 | ⬆️ | Upstream did not honour `options.signal`; genesis forwards it through `httpRequest`. |
|
|
| Upstream test suite (vi.spyOn-based fetch mock) | ✅ | ⬆️ | Rewritten to `@suaveplan/testing/runner` with a recording `FetchLike` closure — no `vi.mock`, no `vi.spyOn`. |
|
|
| Sibling `.md` per source file + ≥200-word README | 🚫 | ⬆️ | Upstream `binance.md` was 46 lines; genesis form ships the §4 doc contract. |
|
|
|
|
No 🚫 row is left without justification.
|
|
|
|
## Impact
|
|
|
|
### Affected dependents
|
|
|
|
Run `bunx turbo ls --filter=...@suaveplan/currency-provider-binance` to
|
|
enumerate.
|
|
|
|
- No current dependents (verified by
|
|
`bunx turbo ls --filter=...@suaveplan/currency-provider-binance` —
|
|
this is a new package and downstream commerce stacks consume it
|
|
through the `CurrencyProviderRegistry` lookup, not by direct import).
|
|
- `@suaveplan/currency-providers` — [ ] tests run / [x] docs reviewed
|
|
/ [x] no action needed (this package consumes the slim core; the
|
|
slim core has no knowledge of any sibling and was not modified)
|
|
- `@suaveplan/currency` — [ ] tests run / [x] docs reviewed / [x] no
|
|
action needed (we depend on the `CurrencyProvider` contract — the
|
|
contract is unchanged)
|
|
|
|
## Migration
|
|
|
|
There is no migration path because this is a new package. Consumers
|
|
that previously used the upstream `BinanceProvider` from the
|
|
pre-slim-refactor `@suaveplan/currency-providers` (which has never
|
|
shipped on genesis) replace:
|
|
|
|
```ts
|
|
// Before — upstream pre-slim-refactor form
|
|
import { BinanceProvider } from "@suaveplan/currency-providers";
|
|
```
|
|
|
|
with:
|
|
|
|
```ts
|
|
// After — genesis sibling form
|
|
import { BinanceProvider } from "@suaveplan/currency-provider-binance";
|
|
```
|
|
|
|
Constructor signatures are compatible: `new BinanceProvider()` and
|
|
`new BinanceProvider({ baseUrl: "…" })` both work unchanged. New
|
|
capabilities (`fetch`, `timeoutMs`) are additive and optional.
|
|
|
|
## Out of scope
|
|
|
|
- The other eight sibling provider packages — each lands under its own
|
|
OpenSpec change per AGENTS.md §0c.
|
|
- Streaming / WebSocket / authenticated endpoints — REST-only for v1.
|
|
- Retry orchestration, circuit breaker, rate-limit accounting — those
|
|
ship as wrapper providers consuming the `CurrencyProvider` contract.
|