@qtsurfer/api-client 0.20.0 → 0.22.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,19 @@ export const getLive = <ThrowOnError extends boolean = false>(
  * (it overrides `getExecutionCallback()`) has no other execution venue, so it cannot start
  * without a `paper` block.
  *
+ * **Warming up.** Pass `warmFrom` to choose how many seconds before its start the run replays the market
+ * feed from, so that its indicators and windows have history when the first live tick arrives. `0` replays
+ * nothing: the run delivers its first signal as soon as it is running, but its indicators start empty and the
+ * first bar of a window can be partial. Omitted, the platform replays from the start of the current 15-minute
+ * block, which is between 0 and 900 seconds before the run's start, so the first bar of a 15-minute window is
+ * complete. The value in effect, yours or the platform's, comes back as `warmFrom`. It can be set only here,
+ * when the run is started. See the "Live execution" guide, "Warming up".
+ *
+ * **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 +1472,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 +1617,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,31 @@ 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;
+  /**
+   * How many seconds before the run's start to replay the market feed from, so the strategy's indicators and
+   * windows have history when its first live tick arrives. `0` replays nothing: the run delivers its first
+   * signal as soon as it is running, but its indicators start empty and the first bar of a window can be
+   * partial. Omitted, the platform replays from the start of the current 15-minute block: between 0 and 900
+   * seconds before the run's start, depending on when it starts (0 if it starts exactly on a quarter hour),
+   * so the first bar of a 15-minute window is complete. The value in effect, the one you sent or the one the
+   * platform chose, is reported back as `warmFrom` on the run. Signals about the replayed time
+   * are not pushed on the run's channel or stream: they describe events from before the run started.
+   * It can be set **only when the run is started**: it is not a parameter of `PUT /live/{runId}/params`, and
+   * changing it means stopping the run and starting it again. Anything that is not an integer from 0 to 3600
+   * is `400`. See the "Live execution" guide, "Warming up".
+   *
+   */
+  warmFrom?: number;
   name?: string;
   description?: string;
   paper?: LivePaperConfig;
@@ -1895,7 +1920,7 @@ export type SendLiveCommandRequest = {
 };
 
 /**
- * A live run's full state, as returned by starting, reading, or stopping it through its strategy.
+ * A live run's full state, as returned by stopping it through its strategy, and the base of the representations returned by starting and by reading it. `warmFrom` is declared by those two (`LiveRunWithStream` and `LiveRunDetail`) and not here, because the response to stopping a run does not carry it.
  */
 export type LiveRun = {
   strategyId: StrategyId;
@@ -1958,6 +1983,109 @@ 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;
+};
+
+/**
+ * The `warmFrom` in effect for this run, in seconds: the one requested when the run was started or, when none was, the one the platform chose (the distance from the run's start back to the start of the current 15-minute block, 0 to 900). It is never `null`. It is present on every run started since the field exists and absent from a run started before it existed. It never changes while the run exists.
+ */
+export type WarmFrom = number;
+
+/**
+ * A run as returned by `GET /live/{runId}`, the full state of `LiveRun` plus when it last changed.
+ */
+export type LiveRunDetail = LiveRun & {
+  warmFrom?: WarmFrom;
+  /**
+   * 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 `warmFrom` (absent only for a run started before the field existed) and 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
+ * returns `LiveRun`, which carries neither `warmFrom` nor the URL, and `GET /live/{runId}` returns `LiveRunDetail`, which carries `warmFrom` and never the URL.
+ *
+ */
+export type LiveRunWithStream = LiveRun & {
+  warmFrom?: WarmFrom;
+  /**
+   * 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 +3826,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 +3847,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. A `warmFrom` that is not an integer from 0 to 3600.
    */
   400: ResponseError;
   /**
@@ -3731,9 +3859,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 +3872,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 +3949,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 +4099,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: {