@taphubhq/sdk-core 0.25.5 → 0.26.0

package/README.md

@@ -1,6 +1,10 @@
 # @taphubhq/sdk-core
 
-Framework-agnostic TypeScript SDK for the TabHub platform.
+Framework-agnostic TypeScript SDK for the TapHub platform. Wraps the grid-api and
+user-service GraphQL endpoints plus the MQTT realtime streams behind one client.
+
+For React bindings (hooks, providers, i18n), use
+[`@taphubhq/sdk-react`](https://github.com/TaphubHQ/taphub-sdk/blob/main/packages/sdk-react/README.md), which builds on this package.
 
 ## Install
 
@@ -16,9 +20,11 @@ import { TaphubClient } from '@taphubhq/sdk-core';
 const client = new TaphubClient({
   agencyId: 'acme-corp',
   // Shared API base. The SDK derives:
-  //   - grid-api    → ${endpoint}/grid-api/grid-gql
+  //   - grid-api     → ${endpoint}/grid-api/grid-gql
   //   - user-service → ${endpoint}/taphub-user-service/th-user-gql
   endpoint: 'https://builder.taptrading.net/api',
+  // Optional — omit to run without realtime (client.realtime stays undefined).
+  mqttEndpoint: 'wss://mqtt.taptrading.net/mqtt',
 });
 
 // Session-token login via user-service GraphQL (preferred).
@@ -27,16 +33,276 @@ await client.auth.loginWithSession(upstreamSessionToken);
 const me = await client.user.me();
 ```
 
-### Login methods
+### Config
+
+| Field          | Required | Notes |
+|----------------|----------|-------|
+| `agencyId`     | yes      | Sent as `x-builder-code` on every request. Also namespaces token storage and scopes agency MQTT topics. |
+| `endpoint`     | yes      | Absolute URL of the shared API base. Must parse as a URL — the constructor throws `TaphubValidationError` (`code: 'InvalidConfig'`) otherwise. |
+| `mqttEndpoint` | no       | When absent, `client.realtime` is `undefined`; every other module still works. |
+| `mqttAuth`     | no       | `{ username, password }`, forwarded verbatim to the broker. For the TapHub/EMQX JWT-in-username setup, pass the session token as `username` and `''` as `password`. Read once when the connection opens — no refresh on reconnect. Ignored without `mqttEndpoint`. |
+| `storage`      | no       | `TaphubStorageAdapter` for token persistence. Defaults to `localStorage` in the browser, in-memory elsewhere. |
+| `fetch`        | no       | Custom `fetch` implementation (SSR, instrumentation, test doubles). |
+
+### Naming: `pairId` vs `agencyPairId`
+
+- **`pairId`** — the system-wide pair id, e.g. `grid-ETH-USD`. **Slash-free** by
+  design so it is safe inside MQTT topics, URLs, and Redis keys. This is what
+  every SDK method takes.
+- **`agencyPairId`** — the agency-scoped composite `{agencyId}:{pairId}`, e.g.
+  `acme-corp:grid-ETH-USD`. The server composes it from your `x-builder-code` /
+  JWT; you only meet it as an MQTT `gameId` and on `PairInfo.agencyPairId`.
+- **`ETH/USD`** is a *display* name (`Pair.pair`, `AgencyPairStats.pair`), never
+  an id.
+
+The pre-`bid-260602-v2` names `game` / `gameId` / `gamePairId` are retired from
+the public surface.
+
+## Client surface
+
+| Accessor            | Module                  | Auth |
+|---------------------|-------------------------|------|
+| `client.auth`       | `AuthModule`            | — |
+| `client.user`       | `UserModule`            | JWT |
+| `client.pair`       | `PairModule`            | JWT (anon-tolerant) |
+| `client.bid`        | `BidModule`             | JWT |
+| `client.leaderboard`| `LeaderboardModule`     | mixed (see below) |
+| `client.agencyPairs`| `AgencyPairModule`      | anon (`x-builder-code`) |
+| `client.locale`     | `LocaleModule`          | anon |
+| `client.realtime`   | `RealtimeModule \| undefined` | broker creds |
+| `client.network`    | `NetworkQualityMonitor` | — |
+
+Token helpers live on the client itself: `getToken()`, `setToken(token, { isDemo })`,
+`isDemo()`.
+
+> **Anon vs JWT reads.** `agencyPairs.list()`, `leaderboard.list()` and
+> `leaderboard.rankBoard()` deliberately send **`x-builder-code` only, never the
+> JWT**. A signed-in user can hold a JWT for a different agency than the one in
+> context (a builder's demo user is always issued a `taptrading` JWT); attaching
+> it would make the backend take its "JWT wins" branch and return the wrong
+> agency's data.
+
+## Auth
+
+```ts
+await client.auth.loginWithSession(sessionToken); // → LoginResult
+await client.auth.logout();
+```
 
-| Method                          | Transport          | Status      |
-|---------------------------------|--------------------|-------------|
+| Method                           | Transport            | Status        |
+|----------------------------------|----------------------|---------------|
 | `loginWithSession(sessionToken)` | user-service GraphQL | **Preferred** |
-| `createDemoUser(username?)`     | grid-api GraphQL    | Active        |
-| `loginWithGoogle(idToken)`      | grid-api REST       | `@deprecated` |
-| `demoLogin(username?)`          | grid-api REST       | `@deprecated` |
+| `createDemoUser(username?, opts?)` | grid-api GraphQL   | Active        |
+| `loginWithGoogle(idToken)`       | grid-api REST        | `@deprecated` |
+| `demoLogin(username?)`           | grid-api REST        | `@deprecated` |
+
+REST-backed methods continue to work until the gateway retires the routes in a
+follow-up change.
+
+## User
+
+```ts
+const me       = await client.user.me();                          // Me
+const pnl      = await client.user.pnl({ period: 'weekly' });     // UserPnL — 'weekly' | '30d'
+const wallets  = await client.user.wallets();                     // UserWallet[]
+const usdc     = await client.user.walletByCurrency('USDC.e');    // UserWallet
+const enabled  = await client.user.refreshCurrencies();           // Currency[]
+client.user.clearCurrencies();                                    // drop the cached list
+```
+
+`UserPnL` carries `gain` (= `totalPayout − totalWagered`), the wagered/payout
+totals, bid/win counts, and both competition ranks (`pnlRank`, `volRank`; `0`
+means unranked).
+
+> `client.user.wallets()` returns `UserWallet` (`{ id, amount, currency, isEnable }`),
+> which is **not** the `Wallet` returned by the auth module (`{ balance, isEnabled }`).
+> The distinct export alias is deliberate — see the note in `src/index.ts`.
+
+## Pairs
+
+```ts
+const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' }); // PairInfo[]
+const pair  = await client.pair.get('grid-ETH-USD');                              // Pair
+const bars  = await client.pair.chartHistory('grid-ETH-USD');                     // Candle[]
+```
+
+- `get(pairId)` throws `TaphubValidationError` with `code: 'GameNotFound'` when
+  the pair has no configured game for the agency in context. It also feeds the
+  clock-offset estimate (see [Clock sync](#clock-sync)).
+- `chartHistory(pairId, limit?)` defaults to `DEFAULT_CHART_HISTORY_LIMIT` (600);
+  the server clamps any request to its cache size (1500).
+- **`Candle.time` from GraphQL is Unix epoch SECONDS.** The MQTT
+  `MqttCandleEvent.time` is **milliseconds**. Do not multiply the MQTT value.
+- `PairInfo.agencyPairId` is populated only for authenticated callers, and is the
+  value to feed into `realtime.subscribe()`.
+- `Pair.config` carries `gridConfig` (`cellSizeTime`, `cellSizeValue`,
+  `candleSize`, `baseline`, `baselineTime`), `constraints`, bid amount bounds, and
+  the effective cancel policy (`bidCancelMinSeconds`, `bidCancelRefundRate`).
+  Treat `undefined` / `0` on the cancel fields as "use the platform default".
+
+## Bids
+
+```ts
+const bid = await client.bid.placeBid({
+  pairId: 'grid-ETH-USD',
+  walletId,                 // required — grid-api's wallet_id is ID!
+  time1, time2,             // window, unix seconds
+  price1, price2,           // decimal strings
+  coefficient: '2.35',
+  amount: '10',
+  slippage: 5,              // tolerance percent
+});
+
+const result = await client.bid.cancelBid(bid.id);   // { bid, refundAmount, newBalance }
+const mine   = await client.bid.listBids({ statuses: ['pending'], limit: 20, pairId });
+```
+
+`placeBid` auto-stamps `ct` (raw client send time) and `clockOffset` at dispatch
+so the server can record skew-corrected latency into `bid.meta`. Both are
+untrusted tracing data — do not supply them yourself.
+
+`listBids` takes `statuses: BidStatus[]` (include-semantics). The singular
+`status` is `@deprecated` and folded into a one-element list; `statuses` wins when
+both are present.
+
+Status classifiers avoid string-literal typos:
+
+```ts
+import { isPending, isTerminal, isWin, isLoss, isCancelled } from '@taphubhq/sdk-core';
+```
+
+`Bid.refundRate` / `Bid.refundAmount` are present only on cancelled bids. Prefer
+`refundAmount` for display — it is the exact credited value, so it needs no
+recompute from a config rate. `Bid.meta.pairName` holds the display pair frozen
+at placement; read it instead of mapping `pairId` yourself.
+
+## Leaderboard & rank
+
+```ts
+const board = await client.leaderboard.rankBoard({
+  period: 'last_7d',        // 'today' | 'yesterday' | 'last_7d' | 'last_30d' | 'all_time' | 'custom'
+  sort: 'pnl',              // 'pnl' | 'vol'
+  sortDir: 'desc',
+  limit: 50, offset: 0,
+});                          // RankBoard — public, identical for every caller
+
+const me = await client.leaderboard.myRank({ period: 'last_7d' }); // MyRank | null
+```
+
+- `period: 'custom'` requires an **hour-aligned** ISO-8601 UTC `range`.
+- The board carries no per-user data by design (`bid-260606-leaderboard-split-my-rank`)
+  so it stays cacheable — `myRank()` is the per-user companion and does attach
+  the JWT. It returns `null` when nobody is signed in, and `MyRank.entry === null`
+  when the caller has no activity in the window.
+- `leaderboard.list({ period, sortBy })` is the v1 query and is `@deprecated` on
+  both the SDK and the backend.
+
+## Agency pairs (market list)
+
+```ts
+const rows = await client.agencyPairs.list({ filter: { status: 'active' } }); // AgencyPairStats[]
+```
+
+Returns the agency-in-context's pairs with `currentPrice`, `currentVol24h`
+(sliding 24h bid-amount sum), `maxCoef`, `thumb`, and `ordering`. There is no
+argument to target another agency by design. Seed your UI from this call, then
+keep it live with `realtime.subscribeAgencyPairStats()` — the backend suppresses
+unchanged ticks, so a subscriber may receive nothing until price or volume moves.
+
+## Locale & error copy
+
+```ts
+const res = await client.locale.get('vi', lastSeenVersion);
+// → { lang, version, notModified, translations }
+```
+
+Pass the last-seen `version` as `knownVersion` to get `{ notModified: true,
+translations: null }` when the body is unchanged, and keep your prior state.
+
+Error copy is a separate catalog keyed by the backend `extensions.code`:
 
-REST-backed methods continue to work until the gateway retires the routes in a follow-up change.
+```ts
+await client.locale.loadErrorMessages(navigator.language); // never throws
+
+// …later, inside a catch:
+showToast(client.locale.errorMessage(e.code, 'Could not place your bid.'));
+
+// with placeholders filled from the error's meta:
+client.locale.errorMessage('Bid_CoefficientMismatch', 'Odds changed — try again.', {
+  serverCoef: e.serverCoef,
+});
+```
+
+- `loadErrorMessages(lang)` is background hydration: it **never throws and never
+  rejects**. Any failure leaves the last-known-good catalog in place — failing to
+  translate an error must not itself become an error. The tag is normalised
+  (region dropped, Chinese scripts kept apart), and concurrent calls for the same
+  language share one request.
+- `errorMessage(code, fallback, meta?)` is **synchronous by design** — error copy
+  is read inside a `catch`, where React hooks are illegal. It returns `fallback`
+  whenever the catalog cannot produce a usable sentence, never an empty string and
+  never the raw code. `meta` fills `{name}` placeholders; unfilled placeholders are
+  stripped so raw braces never reach the user.
+- `getErrorMessages(lang, knownVersion?)` is the throwing sibling, for callers who
+  want to see why a fetch failed.
+- `refresh()` is an admin operation — the backend re-pulls the source sheet for
+  every supported language and requires an `X-API-Key` header.
+
+## Realtime (MQTT)
+
+`client.realtime` is `undefined` unless `mqttEndpoint` was configured. Channels
+are refcounted: N `subscribe()` calls for the same key return the same channel and
+need N matching `unsubscribe()` calls.
+
+```ts
+const channel = client.realtime?.subscribe(agencyPairId, userId); // GameChannel
+channel?.on('candle', (e) => drawCandle(e));         // MqttCandleEvent
+channel?.on('bidAccepted', (e) => addLiveTrade(e));  // MqttBidAcceptedEvent
+channel?.on('bidWon', (e) => celebrate(e));
+channel?.on('bidLost', (e) => dim(e));
+channel?.on('bidCancelled', (e) => remove(e.bidId));
+channel?.on('balanceUpdate', (e) => setBalance(e.balance));
+channel?.on('configUpdate', (e) => setBidBounds(e));
+channel?.on('idealConfigUpdate', (e) => suggestCellSize(e));
+channel?.on('error', (err) => report(err));
+client.realtime?.unsubscribe(agencyPairId, userId);
+```
+
+| Subscription | Key | Emits |
+|---|---|---|
+| `subscribe(gameId, userId?)` | `agencyPairId` (+ user) | `GameChannel` — candle, bid lifecycle, balance, config |
+| `subscribeWallet(userId)` | `userId` | `WalletChannel` — `walletBalanceUpdate` on **every** balance change, no game context |
+| `subscribeUserBids(userId)` | `userId` | `UserBidsChannel` — `bidWon` / `bidLost` across **all** pairs, survives pair switches |
+| `subscribeCandle(pairId, handler)` | `pairId` | raw `MqttCandleEvent`, market-wide public data |
+| `subscribeAgencyPairStats(pairId, handler)` | `pairId` | `MqttAgencyPairStatsEvent` for the client's own agency |
+
+Each has a matching `unsubscribe*`; `disconnect()` tears everything down.
+
+Gotchas worth reading twice:
+
+- **`MqttCandleEvent.time` is MILLISECONDS**, unlike the GraphQL `Candle.time`
+  (seconds). Compare against `CANDLE_EVENT.NEW` / `CANDLE_EVENT.UPDATE` rather
+  than bare string literals.
+- `volatility` is the **fast** σ that prices coefficients; `slowVolatility` is the
+  slow σ used for grid geometry only.
+- `MqttAcceptedBid` mirrors the wire shape, **not** the GraphQL `Bid`:
+  `coordinates` is nested, `coefficient` / `price1` / `price2` are numbers, and
+  `createdAt` is epoch milliseconds. `gameUuid` is `@deprecated` — read `pairId`.
+- Won/lost payloads carry no pair, so the SDK recovers `pairId` from the result
+  topic. `pairIdFromBidResultTopic(topic)` is exported if you parse topics
+  yourself; it returns `undefined` on an unrecognised shape rather than throwing.
+- `subscribeAgencyPairStats` throws `TaphubError` (`code: 'AgencyIdRequired'`) if
+  the client was built without an `agencyId`.
+- `MqttWalletBalanceEvent.reason` is an open enum — unknown values are passed
+  through rather than dropped, so handle the default case.
+
+## Clock sync
+
+`client.pair.get()` brackets its request to measure RTT and records a one-shot
+server-clock offset. `placeBid` then stamps that offset alongside the raw client
+send time. This is best-effort: the estimate is set-once and finite-guarded, so it
+never throws and never blocks the pair load. Nothing to configure — just be aware
+that a client which never calls `pair.get()` reports an offset of `0`.
 
 ## Error Handling
 
@@ -81,6 +347,9 @@ The GraphQL transport classifies errors by the first entry's `extensions.code` a
 
 `TaphubSlippageError extends TaphubValidationError`, so existing `instanceof TaphubValidationError` catch blocks keep working. Place the `TaphubSlippageError` check first when both branches exist.
 
+To turn a thrown `code` into a user-facing sentence, use
+[`client.locale.errorMessage()`](#locale--error-copy) rather than hardcoding copy.
+
 ### Slippage error fallback
 
 `TaphubSlippageError` is only thrown when `extensions.meta.clientCoef`, `extensions.meta.serverCoef`, and `extensions.meta.slippage` are all finite numbers. The `slippage` field is the client-submitted tolerance percent (e.g. `5` for 5%). If `meta` is missing or malformed, the SDK falls back to a generic `TaphubValidationError` with `code === 'Bid_CoefficientMismatch'`. Consumers SHOULD treat the generic fallback as the same user-facing rejection but without typed coefficient access.
@@ -114,6 +383,79 @@ The monitor is always present, even when `mqttEndpoint` is not configured. In SS
 - Connection samples from `navigator.connection` are used only as a cold-start fallback; once 3 real samples accumulate they no longer contribute to the EMA.
 - MQTT QoS1 `puback` timing is not yet plumbed; v1 derives MQTT signal from `connect` / `reconnect` / `disconnect` events only.
 
+## Events
+
+A small client-wide bus for cross-cutting signals:
+
+```ts
+import type { TaphubEventMap } from '@taphubhq/sdk-core';
+// 'auth-expired'   → void
+// 'network:change' → { previous: NetworkQuality; current: NetworkQuality }
+```
+
+## Storage
+
+Token persistence goes through a 3-method adapter, namespaced per agency
+(`taphub:{agencyId}:token`):
+
+```ts
+import { TaphubStorage, autoDetectStorage } from '@taphubhq/sdk-core';
+
+new TaphubClient({ ..., storage: TaphubStorage.memory() }); // SSR / tests
+```
+
+`autoDetectStorage()` is the default: `localStorage` in the browser, in-memory
+elsewhere. Implement `TaphubStorageAdapter` (`get` / `set` / `remove`) for
+anything else.
+
+## Coefficient math
+
+`placeBid` takes a `coefficient`, so a headless client has to compute one before it
+can bid. `calculateCoefficientWrapper` is the model the server validates against —
+the same first-passage computation the grid chart renders with, and the same one
+grid-api runs at placement:
+
+```ts
+import {
+  calculateCoefficientWrapper,
+  type CoefficientInput,
+} from '@taphubhq/sdk-core';
+
+const coefficient = calculateCoefficientWrapper({
+  time1, time2, price1, price2,          // the cell you are bidding on
+  candleTime, candleClose, volatility,   // the live candle
+  coefMults, minCoef,                    // from pair.config
+  cellSizeTime, candleSize,              // from pair.config
+});
+```
+
+A return of `Number.POSITIVE_INFINITY` means the cell cannot be priced right now —
+do not pass it to `placeBid`.
+
+The server stays authoritative: a value that disagrees beyond your `slippage`
+tolerance is rejected with `Bid_CoefficientMismatch` (see
+[Slippage error fallback](#slippage-error-fallback)).
+
+**Candle-interval variants.** `candleSize` is part of `CoefficientInput` but does not
+enter the coefficient: the cell width is measured in bars (`cellSizeTime`), and
+`calculateProbHit` already prices the real seconds window, so dividing by
+`candleSize` a second time would double-penalise the 1m/5m variants by roughly
+60×/300× (`bid-260703`). Pass the value from `pair.config` anyway —
+`computeBaseline` uses it.
+
+### Deprecated helpers
+
+`calculateProbWin` and `calculateProbWin_v2` are **deprecated**. They compute a
+one-sided exceedance probability and ignore `price1`, so they do not match the model
+placement validates against. A coefficient derived from them can pass the
+server's one-directional slippage check and lock a lower payout than the cell is
+worth. Use `calculateCoefficientWrapper`. They remain exported, unchanged, for
+existing callers.
+
+The lower-level pieces — `calculateProbHit`, `roundCoefToSignificantDigits`,
+`computeBaseline`, `normalCDF`, `normalPDF`, `errorFunction`, `adaptiveSimpson` —
+are also exported for consumers that need to build on them directly.
+
 ## License
 
 MIT