@qtsurfer/api-client 0.20.0 → 0.21.0

package/src/generated/sdk.gen.ts

@@ -115,6 +115,9 @@ import type {
   ListPublicLiveData,
   ListPublicLiveResponse,
   ListPublicLiveError,
+  GetLiveRunData,
+  GetLiveRunResponse,
+  GetLiveRunError,
   UpdateLiveData,
   UpdateLiveResponse,
   UpdateLiveError,
@@ -124,6 +127,12 @@ import type {
   SendLiveCommandData,
   SendLiveCommandResponse,
   SendLiveCommandError,
+  RevokeLiveStreamData,
+  RevokeLiveStreamResponse,
+  RevokeLiveStreamError,
+  RotateLiveStreamData,
+  RotateLiveStreamResponse,
+  RotateLiveStreamError,
   GetLiveRunSignalsData,
   GetLiveRunSignalsResponse,
   GetLiveRunSignalsError,
@@ -1289,7 +1298,8 @@ export const getDatasetImport = <ThrowOnError extends boolean = false>(
  * Requests a stop. The run winds down at its own next check-in rather than instantly —
  * poll `GET`/`PATCH` `.../live` and expect `state` to remain `RUNNING` for a short window
  * after `desired` flips to `STOPPED`. Calling this again on an already-stopped run is not an
- * error; it returns the same (unchanged) state.
+ * error; it returns the same (unchanged) state. A stopped run has no stream: its `streamUrl`, if it had one,
+ * stops working and is not in this response.
  *
  */
 export const stopLive = <ThrowOnError extends boolean = false>(
@@ -1315,7 +1325,12 @@ export const stopLive = <ThrowOnError extends boolean = false>(
  * Get this strategy's current (or most recent) live run
  * The run you last started for this strategy — its most complete state, including `params`
  * and the promotion `gate` once the sandbox trial has one to report. Returns the run's last
- * known state even after it has stopped; this endpoint never disappears history.
+ * known state even after it has stopped; this endpoint never disappears history. When the run was started
+ * with a `stream`, `streamUrl` is here too while the run is running and your plan allows it.
+ *
+ * While the run is being executed it also carries `stats`, the run's latest counters (updates
+ * processed, rate, instruments seen), refreshed about once a minute. Starting or stopping a run
+ * does not return them; read them here.
  *
  */
 export const getLive = <ThrowOnError extends boolean = false>(
@@ -1372,6 +1387,11 @@ export const getLive = <ThrowOnError extends boolean = false>(
  * (it overrides `getExecutionCallback()`) has no other execution venue, so it cannot start
  * without a `paper` block.
  *
+ * **A plain WebSocket stream.** Pass `stream: true` to get a secret URL for this run's signals that a simple
+ * client, or a service that passes them on to others, can open as an ordinary WebSocket, from the sandbox stage
+ * on. The URL is in the response (`streamUrl`) and in `GET /strategy/{strategyId}/live`; treat it like a
+ * password. See the "Live execution" guide.
+ *
  */
 export const startLive = <ThrowOnError extends boolean = false>(
   options: Options<StartLiveData, ThrowOnError>
@@ -1444,6 +1464,40 @@ export const listPublicLive = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * Read one of your runs by its id
+ * Owner only, addressed by `runId` directly rather than through its strategy: the run's own
+ * canonical identity, which is what `POST`/`GET`/`DELETE` `.../live`, `GET /live` and
+ * `GET /live/public` all hand out. Use it to re-read one specific run — including one you
+ * stopped long ago or that is no longer your strategy's most recent — without paging through
+ * `GET /live`.
+ *
+ * Returns the same state as `GET /strategy/{strategyId}/live` (`strategyId` is the strategy's
+ * id, and `stats` is there too), plus `updatedAtMs`: when the run last changed, from any cause — a
+ * state change, a promotion, a parameter update, a stop. A refresh of `stats` is not a change of
+ * the run and does not move `updatedAtMs`. A run that is public is reachable by others through
+ * `GET /live/public`, never through this route.
+ *
+ */
+export const getLiveRun = <ThrowOnError extends boolean = false>(
+  options: Options<GetLiveRunData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).get<
+    GetLiveRunResponse,
+    GetLiveRunError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/live/{runId}",
+    ...options,
+  });
+};
+
 /**
  * Change a run's visibility, name, or description
  * Owner only, addressed by `runId` directly rather than through its strategy — this is a
@@ -1555,6 +1609,63 @@ export const sendLiveCommand = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * Revoke a run's stream URL
+ * Revokes a run's stream URL **for good**: connections open on it are closed within about 15 seconds and it
+ * answers `404` from then on. The run itself is not touched, and a stream cannot be added to it again; start
+ * the run again with `stream: true` for a new URL. Owner only, and always allowed, whatever your plan or the
+ * run's state. Repeating it is not an error.
+ *
+ */
+export const revokeLiveStream = <ThrowOnError extends boolean = false>(
+  options: Options<RevokeLiveStreamData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).delete<
+    RevokeLiveStreamResponse,
+    RevokeLiveStreamError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/live/{runId}/stream",
+    ...options,
+  });
+};
+
+/**
+ * Rotate a run's stream URL
+ * Gives a run a **new** stream URL and retires the old one: connections open on the old URL are closed
+ * within about 15 seconds and the old URL answers `404` from then on. Use it when the URL may have leaked.
+ * Owner only, and only for a run that is running and was started with `stream: true` (the URL cannot be added
+ * to a run later, and a revoked one cannot be brought back). The plan is checked again: a plan that may not
+ * broadcast gets `429`.
+ *
+ * See the "Live execution" guide, "A plain WebSocket stream of a run".
+ *
+ */
+export const rotateLiveStream = <ThrowOnError extends boolean = false>(
+  options: Options<RotateLiveStreamData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).post<
+    RotateLiveStreamResponse,
+    RotateLiveStreamError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/live/{runId}/stream",
+    ...options,
+  });
+};
+
 /**
  * Read a run's signals
  * Returns one page of the signals a run has already produced, newest-last, optionally from a

package/src/generated/types.gen.ts

@@ -1821,6 +1821,16 @@ export type StartLiveRequest = {
    * Request that this run's signals be relayed over its WebSocket channel, from its first signal — in the `sandbox` stage too, where only you can subscribe to it. See the "Live execution" guide.
    */
   relay?: boolean;
+  /**
+   * Ask for a **stream URL**: a secret address that a simple client, or a service that passes your signals
+   * on to others, can open as a plain WebSocket to receive this run's signals as they are produced, one JSON
+   * text frame per signal, with none of the live-execution protocol around it. The URL comes back as
+   * `streamUrl` in the response to this call. Available from the `sandbox` stage on, on the plans that may
+   * broadcast; any other plan gets `429`. It can be asked for **only when the run is started** (not added
+   * later), and it also turns `relay` on. See the "Live execution" guide, "A plain WebSocket stream of a run".
+   *
+   */
+  stream?: boolean;
   name?: string;
   description?: string;
   paper?: LivePaperConfig;
@@ -1958,6 +1968,102 @@ export type LiveRun = {
    * The run's paper trading configuration as accepted at start, normalised. Absent when the run has no paper trading.
    */
   paper?: LivePaperConfig;
+  /**
+   * The run's latest counters. Returned by the two reads, `GET /strategy/{strategyId}/live` and
+   * `GET /live/{runId}`; never by starting or stopping a run. Absent until the first snapshot exists
+   * (a run that has just started), and absent is not zero.
+   *
+   */
+  stats?: LiveRunStats;
+};
+
+/**
+ * What a run has been doing, as of its last snapshot. The platform refreshes it about once a minute
+ * while the run is being executed, so `opsPerSecond` is an average over that interval, not an
+ * instantaneous rate.
+ *
+ */
+export type LiveRunStats = {
+  /**
+   * Updates of instruments the run has accepted since it started executing. It can start again from zero if the run is restarted.
+   */
+  processed: number;
+  /**
+   * Updates accepted per second over the last refresh interval. `0` when none arrived.
+   */
+  opsPerSecond: number;
+  /**
+   * How many distinct instruments the run has received an update for.
+   */
+  instrumentsSeen: number;
+  /**
+   * Epoch milliseconds when these counters were last written.
+   */
+  asOfMs: number;
+  /**
+   * Epoch milliseconds of the last snapshot in which `processed` had grown. Absent until the run has
+   * processed anything. A run fed by a source that updates rarely (a funding rate, for example) can
+   * stay flat for hours: that is how such a run behaves, not a fault.
+   *
+   */
+  progressedAtMs?: number;
+  /**
+   * `true` when the run is meant to be running (`desired` is `RUNNING`) and its counters have not
+   * been refreshed for several refresh intervals: the platform has stopped updating them, which is
+   * worth checking against `state`. `false` otherwise. A run whose `processed` is flat is not stale;
+   * `progressedAtMs` is how to tell it apart.
+   *
+   */
+  stale: boolean;
+};
+
+/**
+ * A run as returned by `GET /live/{runId}`, the full state of `LiveRun` plus when it last changed.
+ */
+export type LiveRunDetail = LiveRun & {
+  /**
+   * Epoch milliseconds of the run's last change, from any cause. It only moves forward, so of two reads of the same run the one with the larger value is the newer.
+   */
+  updatedAtMs: number;
+};
+
+/**
+ * A run as `LiveRun` describes it, plus its `streamUrl` when it has one. It is what **starting a run** and
+ * `GET /strategy/{strategyId}/live` return: your own run, read with your own credentials. Stopping a run
+ * and `GET /live/{runId}` return `LiveRun`, which never carries the URL.
+ *
+ */
+export type LiveRunWithStream = LiveRun & {
+  /**
+   * The run's secret stream URL (`wss://…`). **Treat it like a password**: anyone who holds it can read
+   * this run's signals, from the sandbox stage on. Present only when the run was started with
+   * `stream: true`, is wanted running, has not had its stream revoked, and your plan still lets you
+   * broadcast; absent otherwise (a plan that lets you broadcast again gets the same URL back). Rotate
+   * it with `POST /live/{runId}/stream` if it leaks, revoke it with `DELETE /live/{runId}/stream`.
+   *
+   */
+  streamUrl?: string;
+};
+
+/**
+ * A run's new stream URL, as returned by `POST /live/{runId}/stream`.
+ */
+export type LiveStreamUrl = {
+  /**
+   * The run's new secret stream URL. The previous one has stopped working.
+   */
+  streamUrl: string;
+};
+
+/**
+ * What `DELETE /live/{runId}/stream` returns.
+ */
+export type LiveStreamRevoked = {
+  runId: string;
+  /**
+   * Always `true`.
+   */
+  revoked: boolean;
 };
 
 /**
@@ -3698,9 +3804,9 @@ export type GetLiveError = GetLiveErrors[keyof GetLiveErrors];
 
 export type GetLiveResponses = {
   /**
-   * The run's current state
+   * The run's current state, with its `streamUrl` when it has one
    */
-  200: LiveRun;
+  200: LiveRunWithStream;
 };
 
 export type GetLiveResponse = GetLiveResponses[keyof GetLiveResponses];
@@ -3719,7 +3825,7 @@ export type StartLiveData = {
 
 export type StartLiveErrors = {
   /**
-   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), a `type` the strategy cannot consume (a ticker strategy with a `kline` source, or the reverse; the message names both), an invalid `visibility`, an invalid `paper` block (an unknown field, a wrong type or an out-of-range value), or no `paper` block for a strategy that listens to its own execution events.
+   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), a `type` the strategy cannot consume (a ticker strategy with a `kline` source, or the reverse; the message names both), an invalid `visibility`, an invalid `paper` block (an unknown field, a wrong type or an out-of-range value), or no `paper` block for a strategy that listens to its own execution events. A `relay` or `stream` that is not `true` or `false`, or a `stream` where streams are not available yet.
    */
   400: ResponseError;
   /**
@@ -3731,9 +3837,10 @@ export type StartLiveErrors = {
    */
   409: ResponseError;
   /**
-   * Your plan does not include live runs, would exceed your concurrent-run or
-   * instrument-count limit, or the platform is at capacity right now. Carries a
-   * `Retry-After` header.
+   * One of two kinds. **Your plan** does not include live runs, would exceed your concurrent-run or
+   * instrument-count limit, or does not let you ask for a `stream`: the message names your plan, and
+   * retrying will not help until something changes, so there is no `Retry-After`. Or **the platform is at
+   * capacity** right now: a `Retry-After` header says when to try again.
    *
    */
   429: ResponseError;
@@ -3743,9 +3850,9 @@ export type StartLiveError = StartLiveErrors[keyof StartLiveErrors];
 
 export type StartLiveResponses = {
   /**
-   * Started — the run's own state, in the sandbox stage
+   * Started — the run's own state, in the sandbox stage, with its `streamUrl` when you asked for a stream
    */
-  201: LiveRun;
+  201: LiveRunWithStream;
 };
 
 export type StartLiveResponse = StartLiveResponses[keyof StartLiveResponses];
@@ -3820,6 +3927,36 @@ export type ListPublicLiveResponses = {
 export type ListPublicLiveResponse =
   ListPublicLiveResponses[keyof ListPublicLiveResponses];
 
+export type GetLiveRunData = {
+  body?: never;
+  path: {
+    /**
+     * The `runId` from `POST`/`GET`/`DELETE` `.../live`, from `GET /live` or from `GET /live/public`
+     */
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}";
+};
+
+export type GetLiveRunErrors = {
+  /**
+   * No such run, or you do not own it — the two look identical on purpose.
+   */
+  404: ResponseError;
+};
+
+export type GetLiveRunError = GetLiveRunErrors[keyof GetLiveRunErrors];
+
+export type GetLiveRunResponses = {
+  /**
+   * The run
+   */
+  200: LiveRunDetail;
+};
+
+export type GetLiveRunResponse = GetLiveRunResponses[keyof GetLiveRunResponses];
+
 export type UpdateLiveData = {
   body?: UpdateLiveRequest;
   path: {
@@ -3940,6 +4077,78 @@ export type SendLiveCommandResponses = {
 export type SendLiveCommandResponse =
   SendLiveCommandResponses[keyof SendLiveCommandResponses];
 
+export type RevokeLiveStreamData = {
+  body?: never;
+  path: {
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}/stream";
+};
+
+export type RevokeLiveStreamErrors = {
+  /**
+   * No such run, or you do not own it.
+   */
+  404: ResponseError;
+  /**
+   * The run was started without a stream, so there is nothing to revoke.
+   */
+  409: ResponseError;
+};
+
+export type RevokeLiveStreamError =
+  RevokeLiveStreamErrors[keyof RevokeLiveStreamErrors];
+
+export type RevokeLiveStreamResponses = {
+  /**
+   * Revoked (or already revoked).
+   */
+  200: LiveStreamRevoked;
+};
+
+export type RevokeLiveStreamResponse =
+  RevokeLiveStreamResponses[keyof RevokeLiveStreamResponses];
+
+export type RotateLiveStreamData = {
+  body?: never;
+  path: {
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}/stream";
+};
+
+export type RotateLiveStreamErrors = {
+  /**
+   * No such run, or you do not own it.
+   */
+  404: ResponseError;
+  /**
+   * One of three reasons, each its own message: the run was started without a stream; its stream was
+   * revoked (a revoked stream cannot be restored: start the run again with a stream); or the run is stopped.
+   *
+   */
+  409: ResponseError;
+  /**
+   * Your plan does not let you broadcast a run's signals. The message names your plan; retrying will not help until it changes, so there is no `Retry-After`.
+   */
+  429: ResponseError;
+};
+
+export type RotateLiveStreamError =
+  RotateLiveStreamErrors[keyof RotateLiveStreamErrors];
+
+export type RotateLiveStreamResponses = {
+  /**
+   * The new URL.
+   */
+  200: LiveStreamUrl;
+};
+
+export type RotateLiveStreamResponse =
+  RotateLiveStreamResponses[keyof RotateLiveStreamResponses];
+
 export type GetLiveRunSignalsData = {
   body?: never;
   path: {