@0xinsider/sdk 0.19.0 → 0.21.0

package/README.md

@@ -223,80 +223,78 @@ access lapses and returns `credential_status` plus
 paid data routes still return `402 subscription_required` until access is
 renewed.
 
-For `listPreGameSides`, require every row's `category_skill` object and
-compare `meta.category_skill_base_payload_hash` with
-`meta.category_skill_enriched_base_payload_hash` before consuming category
-evidence. The evidence is Polymarket-only, forward-observed, and explicitly
-partial; `degraded` or mismatched hashes must not be treated as a measured edge.
-
-Rows carry `side`, `ranked_at`, `backing_score` and `side_share`. The older
-`piled_side`, `signal_created_at`, `conviction_score` and `smart_score` keys
-carry the same values and stay on the wire. `listSportsEdgeSignals` and
-`listSportsEdgeObservations` remain as deprecated aliases on the deprecated
-`/api/v1/sports-edge-*` paths, which answer with `Deprecation` and successor
-`Link` headers.
-
-### Observation-only pre-game side cohorts
-
-`listPreGameSideObservations` exposes the measured `wider_holder`, the
-overlapping `emerging_pile` projection, and provider-confirmed `in_play`
-cohorts without changing the funded pre-game sides route. The response
-includes `snapshot_as_of` and a
-required snapshot-wide operational/unknown-completeness `degraded` verdict plus
-a per-sport terminal-reason `funnel`; every row is tagged
-`observation_only: true`. Do not route these rows to an order executor.
+### Edge Hunter (Max only)
 
-```ts
-const tennis = await client.listPreGameSideObservations({
-  cohort: "wider_holder",
-  category: "Tennis",
-  limit: 20,
-});
+Read the same experimental board as [Edge Hunter](https://0xinsider.com/sports/edge):
 
-console.log(tennis.degraded, tennis.data, tennis.funnel.sports);
-const previousEtag = tennis.meta.etag;
+```ts
+const board = await client.edgeHunter.get({ horizon_hours: 48 });
+if (board.object === "edge_hunter") {
+  console.log(board.data.total, board.data.rows, board.data.as_of);
+}
 ```
 
-Treat `degraded: true` as partial evidence even when a row or the funnel's
-single terminal reason does not independently expose every contributing
-operational or unknown-completeness failure. `capacity_limited` is different:
-it records intentional bounded provider-work admission, remains accountable in
-the funnel, and does not by itself set `degraded: true`.
-
-All category and all-sports cache scopes share one global observation
-provider-work admission. Healthy `wider_holder` requests may reuse a snapshot
-for about 180 seconds. `emerging_pile` projects `wider_holder` rows with finite
-`sharp_pct` in the `[0.75, 0.85)` band, `holder_scan_complete: true`, and a
-kickoff after the first-page projection cutoff. It overlaps the `wider_holder`
-source and is not arrival history or an independent denominator. `in_play`
-never serves a cached observation snapshot older than about 30 seconds and
-fails closed when the provider live-board snapshot is stale or unavailable.
-
-The SDK copies a successful response's weak semantic `ETag` header into
-`meta.etag`; it is client metadata, not an additional field in the server's
-JSON body. The validator covers the stable page payload, including the stable
-page position in `next_cursor`, but excludes request-specific `meta` and, for
-`emerging_pile`, the opaque projection cutoff inside that cursor.
-
-For a conditional request, use `listPreGameSideObservationsConditional()` so a
-`304` returns the typed `{ object: "not_modified", data: null, meta }` result
-while a `200` retains the full observation response type:
+The board covers all sports and esports, uses a fixed B grade floor, and returns
+at most 30 ranked rows. `total` counts rows before that cap. `horizon_hours`
+defaults to 48 and is clamped to 1..48. The default board accepts only `view` and `horizon_hours` and has no ETag or pagination.
+
+Every row includes provider participants, both outcome quotes, and backed-side
+analytics. Current prices are decimal strings with their own `basis`, `ts`,
+and optional `validated_at`; compare those clocks independently from `as_of`.
+Null means unavailable. `ranking_source: "db_only"` and
+`directional_source: "degraded"` identify weaker evidence. This board is
+analytics, not an instruction to place an order.
+
+A Pro credential throws `MaxPlanRequiredError` (403 `forbidden`,
+`reason: max_plan_required`); every other Pro route keeps working with the
+same key. All four previous sports-edge and pre-game-side paths are retired
+and return 410 `endpoint_retired`. Their list and conditional-read methods
+were removed in SDK 0.20.0. Migrate to `client.edgeHunter.get()`.
+SDK 0.21.0 preserves the default board and adds the complete advanced contracts:
 
 ```ts
-import { isApiNotModifiedResponse } from "@0xinsider/sdk";
-
-if (previousEtag) {
-  const conditional = await client.listPreGameSideObservationsConditional(
-    { cohort: "wider_holder", category: "Tennis", limit: 20 },
-    {
-      headers: { "If-None-Match": previousEtag },
-    },
-  );
+const signals = await client.edgeHunter.get({ view: "signals", category: "Soccer", min_grade: "A", limit: 20 });
+if (signals.object === "list") console.log(signals.view, signals.data, signals.next_cursor);
 
-  if (isApiNotModifiedResponse(conditional)) {
-    console.log("snapshot unchanged");
-  }
-}
+const observations = await client.edgeHunter.observations({ cohort: "in_play", limit: 20 });
+if (observations.object === "list") console.log(observations.snapshot_as_of, observations.degraded, observations.funnel);
+
+const unchanged = await client.edgeHunter.getConditional(
+  { view: "observations", cohort: "in_play" },
+  { headers: { "If-None-Match": observations.meta.etag ?? "" } },
+);
+if (unchanged.object === "not_modified") console.log("Unchanged snapshot");
+```
+
+`view: "signals"` returns full ranked records, nullable `token_id`, snapshot clocks,
+holder/directional analytics, category evidence and provenance. It accepts `category`,
+`min_grade` (S/A/B, default B), `horizon_hours` (default 12, clamp 1..48), `limit`
+(default 20, clamp 1..100) and `cursor`. Grade floor requires a holder at that grade or better;
+it does not remove other holders. `signals()` is a convenience for the same mode.
+
+`view: "observations"` requires `cohort` (`wider_holder`, `in_play`, `emerging_pile`)
+and accepts `category`, `limit` and `cursor`. Records preserve verified token IDs,
+midpoint `backed_price` marks, observation/holder clocks, provider/directional status,
+and completeness. The envelope retains `snapshot_as_of`, `degraded` and all per-sport
+funnel diagnostics. Price marks are not wallet entry costs; volume is shares.
+In-play reuse is capped at 30 seconds and fails closed without fresh source evidence.
+
+Literal view queries have distinct result types, including on empty pages. Advanced
+responses add `view: "signals" | "observations"` beside `object: "list"`. Both advanced
+views support ETag/304 and private revalidation. They read warmed generations only;
+missing/stale readiness returns 503 `read_model_warming` with `Retry-After: 5`
+without running holder/provider computation in the request. `getConditional()`
+accepts advanced views only. Parameters for another view return 400, and a refreshed
+snapshot expires its cursors. Start a new cursor walk when migrating from retired URLs.
+The shared `list()`, `paginate()`, `paginatePages()` and `collect()` helpers accept
+Edge Hunter only with an explicit advanced view and preserve the corresponding record
+and envelope types:
+
+```ts
+for await (const page of paginatePages(client, "getEdgeHunter", {
+  query: { view: "observations", cohort: "wider_holder", limit: 100 },
+  maxPages: 2,
+})) console.log(page.view, page.funnel, page.data);
 ```
 
 ### Beyond the JSON envelope
@@ -397,7 +395,7 @@ for await (const trade of paginate(client, "listWhaleTrades", {
 }
 ```
 
-The loop ends when a page says `has_more: false`, whatever its `next_cursor` says. A page that says `has_more: true` with no usable `next_cursor`, or one whose `next_cursor` repeats a cursor the walk already requested, is a broken response rather than the end of the collection: the walk throws `PaginationError` (`reason` `missing_cursor` or `repeated_cursor`) before yielding that page and before any duplicate request, with the received `page` on the error so its data is not lost. The last 1,024 cursors are remembered for the repeat check (`CURSOR_HISTORY_LIMIT`), which keeps a long walk's memory flat. A list response whose `has_more` is not a boolean or whose `next_cursor` is not a string throws `InvalidResponseError`.
+The loop ends when a page says `has_more: false`, whatever its `next_cursor` says. A page that says `has_more: true` with no usable `next_cursor`, or one whose `next_cursor` repeats a cursor the walk already requested, is a broken response rather than the end of the collection: the walk throws `PaginationError` (`reason` `missing_cursor` or `repeated_cursor`) before yielding that page and before any duplicate request, with the received `page` on the error so its data is not lost. The last 1,024 cursors are remembered for the repeat check (`CURSOR_HISTORY_LIMIT`), which keeps a long walk's memory flat. A list response whose `has_more` is not a boolean or whose `next_cursor` is neither a string, null nor omitted throws `InvalidResponseError`. A null terminal cursor is preserved for Edge Hunter observations.
 
 `maxPages` caps fetches and is checked before any request: a positive integer or `Infinity`; `0`, a negative, fractional or `NaN` value throws `RangeError`. Reaching it is your choice, not exhaustion. Pass a `progress` object to tell the two apart and keep the continuation: