@0xinsider/mcp 2.1.3 → 2.6.0

package/dist/sdk/client.js

@@ -19,7 +19,8 @@
  *  - Extra typed convenience methods for list/candle/webhook-event/stream
  *    surfaces and a typed `Grade` enum.
  */
-import { errorFromResponse, OxinsiderApiError, InvalidResponseError, RequestTimeoutError, } from "./errors.js";
+import { createHash } from "node:crypto";
+import { errorFromResponse, ExportIntegrityError, OxinsiderApiError, InvalidResponseError, RequestTimeoutError, } from "./errors.js";
 import { RETRY_AFTER_CEILING_MS, retryAfterSeconds, sleepUnlessAborted, } from "./retry.js";
 /**
  * The full V1 operation table. One row per OpenAPI operation with a
@@ -119,6 +120,12 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "getTraderExportStatus",
         auth: "bearer",
     },
+    {
+        method: "POST",
+        path: "/api/v1/trader/{address}/export/cancel",
+        operationId: "cancelTraderExport",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/leaderboard/trending",
@@ -128,6 +135,18 @@ export const API_CLIENT_OPERATIONS = [
     // Pre-existing gap, fixed here (#7209): the route has shipped in openapi.json,
     // llms-full.txt, agents.md, and the discovery doc, but never in the SDK table --
     // so `drift.test.ts` was RED on main and SDK users had no typed method for it.
+    {
+        method: "GET",
+        path: "/api/v1/sports/pre-game-sides",
+        operationId: "listPreGameSides",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/sports/pre-game-side-observations",
+        operationId: "listPreGameSideObservations",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/sports-edge-signals",
@@ -140,6 +159,48 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "listSportsEdgeObservations",
         auth: "bearer",
     },
+    {
+        method: "GET",
+        path: "/api/v1/games",
+        operationId: "listGames",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/games/{event_slug}",
+        operationId: "getGame",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades",
+        operationId: "listLargeTrades",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/history",
+        operationId: "listLargeTradeHistory",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}/counterparties/executions",
+        operationId: "listLargeTradeCounterpartyExecutions",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}/counterparties/executions/{execution_id}/makers",
+        operationId: "listLargeTradeCounterpartyMakers",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}",
+        operationId: "getLargeTrade",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/whale-trades",
@@ -249,6 +310,22 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "getMarketCandles",
         auth: "bearer",
     },
+    {
+        method: "GET",
+        path: "/api/v1/suspicious-trades",
+        operationId: "listSuspiciousTrades",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/suspicious-trades/{id}",
+        operationId: "getSuspiciousTrade",
+        auth: "bearer",
+    },
+    // Deprecated aliases (#16301). Both paths stay live with no retirement
+    // date; responses carry Deprecation and a Link rel="successor-version".
+    // `/api/v1/insider-radar/{id}` also keeps answering `object: "radar_flag"`,
+    // so these entries are what an existing integration must keep exercising.
     {
         method: "GET",
         path: "/api/v1/insider-radar",
@@ -502,11 +579,26 @@ export const READ_ONLY_POST_OPERATIONS = [
     "batchGetTraders",
     "batchGetMarketIntel",
 ];
+/**
+ * Writes whose repeat converges on the state the first one reached, so a
+ * retry cannot repeat a side effect and needs no `Idempotency-Key` (#16254).
+ * `POST /api/v1/trader/{address}/export/cancel` moves a job at most once and
+ * answers its current state every time: a second cancel of a cancelled job
+ * returns it unchanged, and a cancel that lost the race to a finished file
+ * returns the ready job. They are retried like a read; the API does not read
+ * an `Idempotency-Key` on them, so one is refused like on any other write.
+ */
+export const CONVERGENT_WRITE_OPERATIONS = [
+    "cancelTraderExport",
+];
 const idempotentWrites = new Set(IDEMPOTENT_WRITE_OPERATIONS);
 const readOnlyPosts = new Set(READ_ONLY_POST_OPERATIONS);
+const convergentWrites = new Set(CONVERGENT_WRITE_OPERATIONS);
 /** The retry class of an operation; see `RetryEligibility`. */
 export function retryEligibility(operation) {
-    if (operation.method === "GET" || readOnlyPosts.has(operation.operationId)) {
+    if (operation.method === "GET" ||
+        readOnlyPosts.has(operation.operationId) ||
+        convergentWrites.has(operation.operationId)) {
         return "read";
     }
     return idempotentWrites.has(operation.operationId) ? "keyed" : "never";
@@ -522,8 +614,11 @@ export const DEFAULT_BASE_URL = "https://api.0xinsider.com";
  * The sandbox server, the second `servers` entry of the OpenAPI document: no
  * credential, no production data, every documented operation answered with
  * its example or a deterministic sample, `?sandbox_status=<code>` for a
- * documented error, and `X-Oxi-Sandbox: true` on every response. Streams and
- * file downloads are not simulated there and answer 400.
+ * documented error, and `X-Oxi-Sandbox: true` on every response. The two
+ * Markdown documents answer `200 text/markdown` there and the export download
+ * answers its `302` to a sample file the sandbox serves itself. `GET
+ * /api/v1/stream` is the one operation it does not simulate and answers 400,
+ * because an SSE stream is a live connection rather than a body.
  */
 export const SANDBOX_BASE_URL = "https://0xinsider.com/sandbox";
 /** A live secret key starts with this; the sandbox never needs one. */
@@ -651,6 +746,101 @@ function composeRequestSignal(timeoutMs, caller) {
     }
     return { signal: controller.signal, dispose };
 }
+/**
+ * `response` with `dispose` deferred to the end of its body: the stream's
+ * close, error or cancellation (#16686). Without a `dispose` (a runtime with
+ * `AbortSignal.any`, or no composition) the response is returned as is.
+ */
+function releaseWhenBodySettles(response, dispose) {
+    if (!dispose)
+        return response;
+    if (!response.body) {
+        dispose();
+        return response;
+    }
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    dispose();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (error) {
+                dispose();
+                controller.error(error);
+            }
+        },
+        cancel(reason) {
+            dispose();
+            return reader.cancel(reason);
+        },
+    });
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/**
+ * Hash the bytes a caller actually receives while preserving streaming. The
+ * object is gzip encoded at rest, but fetch exposes the decoded content stream
+ * to Node callers, which is the byte domain covered by content_sha256.
+ */
+function verifyExportBody(response, jobId, expectedSha256, expectedSizeBytes) {
+    if (!response.body) {
+        throw new ExportIntegrityError(jobId, expectedSha256, null, expectedSizeBytes, 0);
+    }
+    const reader = response.body.getReader();
+    const hasher = createHash("sha256");
+    let actualSizeBytes = 0;
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    const actualSha256 = hasher.digest("hex");
+                    if (actualSizeBytes !== expectedSizeBytes ||
+                        actualSha256 !== expectedSha256) {
+                        controller.error(new ExportIntegrityError(jobId, expectedSha256, actualSha256, expectedSizeBytes, actualSizeBytes));
+                        return;
+                    }
+                    controller.close();
+                    return;
+                }
+                if (value === undefined) {
+                    controller.error(new ExportIntegrityError(jobId, expectedSha256, null, expectedSizeBytes, actualSizeBytes));
+                    return;
+                }
+                hasher.update(value);
+                actualSizeBytes += value.byteLength;
+                controller.enqueue(value);
+            }
+            catch (error) {
+                controller.error(new ExportIntegrityError(jobId, expectedSha256, null, expectedSizeBytes, actualSizeBytes, error));
+            }
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/** JSON-RPC methods `POST /api/v1/mcp` answers without a credential. */
+function isKeylessMcpMethod(method) {
+    return (method === "initialize" ||
+        method === "ping" ||
+        method === "tools/list" ||
+        method.startsWith("notifications/"));
+}
 function isTimeoutAbort(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -861,7 +1051,11 @@ export class OxinsiderApiClient {
      * listed.response?.result;
      */
     async mcp(request, options = {}) {
-        const operation = this.resolveOperation("createMcpJsonRpcResponse", "jsonrpc");
+        // `initialize`, `ping`, `tools/list` and the notifications need no
+        // credential (`backend/src/mcp/mod.rs`); only `tools/call` does, so the
+        // local credential check is per method (#16686). A configured key is
+        // still sent on every method.
+        const operation = this.resolveOperation("createMcpJsonRpcResponse", "jsonrpc", !isKeylessMcpMethod(request.method));
         const { sessionId, protocolVersion, ...transportOptions } = options;
         const headers = { ...options.headers };
         if (sessionId !== undefined) {
@@ -870,7 +1064,9 @@ export class OxinsiderApiClient {
         if (protocolVersion !== undefined) {
             headers["mcp-protocol-version"] = protocolVersion;
         }
-        const body = { jsonrpc: "2.0", ...request };
+        // Set after the spread: an explicit `jsonrpc: undefined` would otherwise
+        // drop the field and the server would answer 400 (#16686).
+        const body = { ...request, jsonrpc: "2.0" };
         return this.request(operation, { ...transportOptions, headers, body, maxRetries: 0 }, async (response) => {
             const sessionId = response.headers.get("mcp-session-id");
             const result = {
@@ -888,6 +1084,18 @@ export class OxinsiderApiClient {
             return result;
         });
     }
+    /**
+     * Read the owner-authorized lifecycle and artifact manifest for one export
+     * job. The manifest is immutable for the artifact; the download URL remains
+     * temporary and is resolved separately.
+     */
+    getTraderExportStatus(address, jobId, options = {}) {
+        return this.call("getTraderExportStatus", {
+            ...options,
+            path: { address },
+            query: { job_id: jobId },
+        });
+    }
     /**
      * Resolve the presigned object URL behind `GET /api/v1/trader/{address}/export/download`
      * without downloading anything (#16137).
@@ -941,8 +1149,20 @@ export class OxinsiderApiClient {
      * await pipeline(Readable.fromWeb(response.body), createWriteStream(filename ?? "export.json"));
      */
     async downloadTraderExport(address, jobId, options = {}) {
-        const target = await this.getTraderExportDownloadUrl(address, jobId, options);
-        const downloadSignal = composeRequestSignal(options.downloadTimeoutMs ?? null, options.signal);
+        const { verifyChecksum = false, downloadTimeoutMs, ...requestOptions } = options;
+        let manifest = null;
+        if (verifyChecksum) {
+            const status = await this.getTraderExportStatus(address, jobId, requestOptions);
+            if (isApiNotModifiedResponse(status)) {
+                throw new InvalidResponseError(304, `Export job ${String(jobId)} status was not modified, so its manifest could not be verified. Omit If-None-Match when verifyChecksum is enabled.`, status);
+            }
+            if (status.data.status !== "ready" || !status.data.artifact?.manifest) {
+                throw new InvalidResponseError(200, `Export job ${String(jobId)} did not return a ready artifact manifest, so verifyChecksum cannot verify the download. Wait for status=ready or request a fresh export.`, status);
+            }
+            manifest = status.data.artifact.manifest;
+        }
+        const target = await this.getTraderExportDownloadUrl(address, jobId, requestOptions);
+        const downloadSignal = composeRequestSignal(downloadTimeoutMs ?? null, options.signal);
         let response;
         try {
             // No headers, and no credentials: the presigned URL authorizes itself,
@@ -953,12 +1173,21 @@ export class OxinsiderApiClient {
                 signal: downloadSignal.signal,
             });
         }
-        finally {
+        catch (error) {
             downloadSignal.dispose?.();
+            throw error;
         }
         if (!response.ok) {
+            downloadSignal.dispose?.();
             throw new InvalidResponseError(response.status, `The presigned export URL answered ${response.status}. A presigned link is valid for about an hour; request a fresh one with getTraderExportDownloadUrl.`, null);
         }
+        // The caller reads the body after this returns, so the composed signal
+        // (caller abort plus `downloadTimeoutMs`) stays wired until the body ends
+        // or is cancelled, not only until the headers arrive (#16686).
+        response = releaseWhenBodySettles(response, downloadSignal.dispose);
+        if (manifest) {
+            response = verifyExportBody(response, jobId, manifest.content_sha256, manifest.content_size_bytes);
+        }
         const contentLength = response.headers.get("content-length");
         return {
             ...target,
@@ -966,13 +1195,20 @@ export class OxinsiderApiClient {
             contentLength: contentLength === null ? null : Number.parseInt(contentLength, 10),
             contentType: response.headers.get("content-type"),
             filename: filenameFromDisposition(response.headers.get("content-disposition")),
+            integrity: manifest
+                ? {
+                    algorithm: "sha256",
+                    expectedSha256: manifest.content_sha256,
+                    expectedSizeBytes: manifest.content_size_bytes,
+                }
+                : null,
         };
     }
     /**
      * Look up an operation and refuse it when the caller reached for the wrong
      * reader (#16137): `call()` on a Markdown route used to fail as a bad 200.
      */
-    resolveOperation(operationId, expected) {
+    resolveOperation(operationId, expected, requireCredential = true) {
         const operation = operationsById.get(operationId);
         if (!operation) {
             throw new Error(`Unknown 0xinsider API operation: ${operationId}`);
@@ -983,7 +1219,7 @@ export class OxinsiderApiClient {
         }
         // The sandbox answers every operation without a credential; production
         // does not, and the local check saves a round trip that can only be 401.
-        if (operation.auth === "bearer" && !this.apiKey && !this.sandbox) {
+        if (requireCredential && operation.auth === "bearer" && !this.apiKey && !this.sandbox) {
             throw new Error(`${operationId} requires an API key (oxi_sk_*)`);
         }
         return operation;
@@ -1167,9 +1403,17 @@ export class OxinsiderApiClient {
     listTrendingWallets(params = {}, options = {}) {
         return this.list("listTrendingWallets", { ...options, query: params });
     }
+    listLargeTrades(params = {}, options = {}) {
+        return this.list("listLargeTrades", { ...options, query: params });
+    }
+    listLargeTradeHistory(params = {}, options = {}) {
+        return this.list("listLargeTradeHistory", { ...options, query: params });
+    }
+    /** @deprecated Use {@link listLargeTrades} (#16304); calls the deprecated `/api/v1/whale-trades`. */
     listWhaleTrades(params = {}, options = {}) {
         return this.list("listWhaleTrades", { ...options, query: params });
     }
+    /** @deprecated Use {@link listLargeTradeHistory} (#16304); calls the deprecated `/api/v1/whale-trades/history`. */
     listWhaleTradeHistory(params = {}, options = {}) {
         return this.list("listWhaleTradeHistory", { ...options, query: params });
     }
@@ -1179,16 +1423,54 @@ export class OxinsiderApiClient {
     listLargePositions(params = {}, options = {}) {
         return this.list("listLargePositions", { ...options, query: params });
     }
+    /**
+     * List ranked sharp-money flows. Canonical since #16308 ("sharp money" is
+     * the pinned product term); it calls `/api/v1/markets/sharp-money-flows`.
+     */
+    listSharpMoneyFlows(params = {}, options = {}) {
+        return this.list("listSharpMoneyFlows", { ...options, query: params });
+    }
+    /**
+     * @deprecated Use {@link listSharpMoneyFlows} (#16308). Kept live; it calls
+     * the deprecated `/api/v1/markets/smart-money-flows`, whose responses carry
+     * `Deprecation` and a `Link rel="successor-version"`.
+     */
     listSmartMoneyFlows(params = {}, options = {}) {
         return this.list("listSmartMoneyFlows", { ...options, query: params });
     }
-    /** Canonical alias of {@link listSmartMoneyFlows} (epic #6912). */
-    listSharpMoneyFlows(params = {}, options = {}) {
-        return this.list("listSharpMoneyFlows", { ...options, query: params });
+    /**
+     * List covered games: both sides with their provider ids and live scores, the
+     * UTC kickoff, the provider's own status, and every linked Polymarket market
+     * with its condition id and outcome token ids. Ordered by kickoff, then by
+     * `event_slug`, with unscheduled games last. An unknown `sport` or `status`
+     * returns an empty page rather than an error, and the response's `coverage`
+     * names what this deployment serves.
+     */
+    listGames(params = {}, options = {}) {
+        return this.list("listGames", { ...options, query: params });
+    }
+    /**
+     * Read one game by its `event_slug`, the identity the `live_sports_updated`
+     * webhook pulse carries. A slug outside the published coverage returns 404.
+     */
+    getGame(eventSlug, options = {}) {
+        return this.call("getGame", { ...options, path: { event_slug: eventSlug } });
+    }
+    /**
+     * List upcoming games ranked by the side profitable wallets hold, with
+     * additive, shadow-only category evidence. `category_skill` never changes
+     * membership, ordering, or sizing. 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.
+     */
+    listPreGameSides(params = {}, options = {}) {
+        return this.list("listPreGameSides", { ...options, query: params });
     }
     /**
-     * List the funded-primary sports signals with additive, shadow-only category
-     * evidence. `category_skill` never changes membership, ordering, or sizing.
+     * @deprecated Use {@link listPreGameSides} (#16310). Kept live; it calls the
+     * deprecated `/api/v1/sports-edge-signals` path, which answers with
+     * `Deprecation` and successor `Link` headers and the same body.
      */
     listSportsEdgeSignals(params = {}, options = {}) {
         return this.list("listSportsEdgeSignals", { ...options, query: params });
@@ -1202,6 +1484,18 @@ export class OxinsiderApiClient {
      * additive wider-holder projection, not an arrival-history or independent
      * denominator view.
      */
+    async listPreGameSideObservations(params, options = {}) {
+        const response = await this.list("listPreGameSideObservations", {
+            ...options,
+            query: params,
+        });
+        return sportsEdgeObservationsResponse(response);
+    }
+    /**
+     * @deprecated Use {@link listPreGameSideObservations} (#16310). Kept live; it
+     * calls the deprecated `/api/v1/sports-edge-observations` path, which answers
+     * with `Deprecation` and successor `Link` headers and the same body.
+     */
     async listSportsEdgeObservations(params, options = {}) {
         const response = await this.list("listSportsEdgeObservations", {
             ...options,
@@ -1218,6 +1512,20 @@ export class OxinsiderApiClient {
      * projection cutoff inside `next_cursor` is excluded while its stable page
      * position remains covered.
      */
+    async listPreGameSideObservationsConditional(params, options = {}) {
+        const response = await this.call("listPreGameSideObservations", {
+            ...options,
+            query: params,
+        });
+        if (isNotModified(response)) {
+            return response;
+        }
+        return sportsEdgeObservationsResponse(response);
+    }
+    /**
+     * @deprecated Use {@link listPreGameSideObservationsConditional} (#16310).
+     * Kept live on the deprecated `/api/v1/sports-edge-observations` path.
+     */
     async listSportsEdgeObservationsConditional(params, options = {}) {
         const response = await this.call("listSportsEdgeObservations", {
             ...options,
@@ -1280,15 +1588,62 @@ export class OxinsiderApiClient {
             query: params,
         });
     }
+    /**
+     * Fetch one suspicious trade by raw `whale_alerts.id` or the `rf_`-prefixed
+     * id list responses emit. The envelope's `object` is `"suspicious_trade"`.
+     */
+    getSuspiciousTrade(id, options = {}) {
+        return this.call("getSuspiciousTrade", { ...options, path: { id } });
+    }
+    /** List stored trades whose recorded suspicion score meets the flag threshold. */
+    listSuspiciousTrades(params = {}, options = {}) {
+        return this.list("listSuspiciousTrades", { ...options, query: params });
+    }
+    /**
+     * @deprecated Use `getSuspiciousTrade()`; renamed in #16301. This method
+     * keeps calling the deprecated `GET /api/v1/insider-radar/{id}`, which stays
+     * live with no retirement date and still answers `object: "radar_flag"`, so
+     * an integration branching on that envelope keeps working.
+     */
     getInsiderRadarFlag(id, options = {}) {
         return this.call("getInsiderRadarFlag", { ...options, path: { id } });
     }
+    /**
+     * @deprecated Use `listSuspiciousTrades()`; renamed in #16301. This method
+     * keeps calling the deprecated `GET /api/v1/insider-radar`, which stays live
+     * with no retirement date and answers with `Deprecation` plus a `Link
+     * rel="successor-version"` header.
+     */
     listInsiderRadar(params = {}, options = {}) {
         return this.list("listInsiderRadar", { ...options, query: params });
     }
+    getLargeTrade(id, options = {}) {
+        return this.call("getLargeTrade", { ...options, path: { id } });
+    }
+    /** @deprecated Use {@link getLargeTrade} (#16304); calls the deprecated `/api/v1/whale-trades/{id}`. */
     getWhaleTrade(id, options = {}) {
         return this.call("getWhaleTrade", { ...options, path: { id } });
     }
+    // --- Exports ---
+    /**
+     * Cancel a submitted export (`POST /api/v1/trader/{address}/export/cancel`, #16254).
+     *
+     * Resolves to the job resource after the cancel, the same shape
+     * `getTraderExportStatus` returns: `cancelled` for a job no worker had
+     * started, `cancel_requested` for a running one (poll the status route at
+     * `poll_after_s` until it reads `cancelled`), or the job unchanged when a
+     * cancel can no longer reach it (its file is being published, or it is
+     * already terminal). Compare `status` rather than assuming success. A
+     * cancel never deletes a ready file, never returns quota, and is safe to
+     * repeat, so it is retried on a transport or 5xx failure like a read.
+     */
+    cancelTraderExport(address, jobId, options = {}) {
+        return this.call("cancelTraderExport", {
+            ...options,
+            path: { address },
+            query: { job_id: jobId },
+        });
+    }
     // --- Webhooks ---
     listWebhooks(options = {}) {
         return this.list("listWebhooks", options);