@qtsurfer/api-client 0.19.0 → 0.20.0

package/src/generated/sdk.gen.ts

@@ -121,6 +121,9 @@ import type {
   UpdateLiveParamsData,
   UpdateLiveParamsResponse,
   UpdateLiveParamsError,
+  SendLiveCommandData,
+  SendLiveCommandResponse,
+  SendLiveCommandError,
   GetLiveRunSignalsData,
   GetLiveRunSignalsResponse,
   GetLiveRunSignalsError,
@@ -374,6 +377,10 @@ export const downloadKlines = <ThrowOnError extends boolean = false>(
  * many strategies you have. Check a specific strategy's validation with `GET
  * /strategy/{strategyId}`.
  *
+ * With `includeDeleted=true`, strategies you have deleted are listed too, each with the
+ * `deletedAt` it was deleted at — useful to keep a copy of your list in sync, telling a
+ * deleted strategy apart from one that never existed.
+ *
  */
 export const listStrategies = <ThrowOnError extends boolean = false>(
   options?: Options<ListStrategiesData, ThrowOnError>
@@ -411,6 +418,11 @@ export const listStrategies = <ThrowOnError extends boolean = false>(
  * included, is read from `GET /strategy/{strategyId}`. One place to ask, so there is no second
  * answer to keep in step.
  *
+ * A `200` means the source parsed and compiled, not that it will run. What only shows once the
+ * strategy sets up its indicators is found by `validate`: for QTScript, a window on an indicator
+ * name that is not registered (`window nosuch m1 { ... }`) registers, and `validate` ends `failed`
+ * on that line.
+ *
  * For **Java**, the `strategyId` is derived from what the code *means*, not from how it is
  * written. Adding a comment, inserting a blank line, re-indenting, reordering imports, or
  * moving a method around all return the **same** id — you have not created a second strategy.
@@ -976,6 +988,10 @@ export const getBacktestResult = <ThrowOnError extends boolean = false>(
  * Every dataset you have created and not deleted, most recently created first. Never a `404`
  * — an empty array if you have none, same convention as `GET /strategies`.
  *
+ * With `includeDeleted=true`, datasets you have deleted are listed too, each with the
+ * `deletedAt` it was deleted at — useful to keep a copy of your list in sync, telling a
+ * deleted dataset apart from one that never existed.
+ *
  */
 export const listDatasets = <ThrowOnError extends boolean = false>(
   options?: Options<ListDatasetsData, ThrowOnError>
@@ -1408,8 +1424,9 @@ export const listLive = <ThrowOnError extends boolean = false>(
 
 /**
  * Browse public live runs
- * Every run whose owner marked it `public` and is currently live and running — anyone's,
- * yours included, and listed without revealing who owns it. Most recently started first.
+ * Every run whose owner marked it `public`, that has been promoted to `live` and is running —
+ * anyone's, yours included, and listed without revealing who owns it. A `public` run still in
+ * its `sandbox` trial is not listed. Most recently started first.
  *
  * This is the only `Live Execution` endpoint that needs no `Authorization` header.
  *
@@ -1498,6 +1515,46 @@ export const updateLiveParams = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * Tell a running strategy a command
+ * Tells a running strategy something **while it stays live**, without restarting it — for a strategy that
+ * implements the engine's `CommandRequestHandler`. Owner only.
+ *
+ * A command is an event, not a stored setting: it is delivered once to every execution behind the run, at
+ * the same market position, and nothing about it is written to the run's state. **It is transient** — a
+ * replica that restarts replays only its recent market history, so a command from before that only reaches
+ * one that was already running when it arrived. Anything the strategy needs to remember across a restart
+ * belongs in a parameter (`PUT /live/{runId}/params`), which does have a stored value; a command does not.
+ *
+ * The command's text is a plain string; an optional `properties` object of your own choosing travels
+ * alongside it. Each entry lands as a top-level entry on the `CommandRequest` the handler receives —
+ * `request.get("<key>")` in Java, `$command.<key>` sugar in QTScript — no key is off limits, since the
+ * command's own text is kept separately.
+ *
+ */
+export const sendLiveCommand = <ThrowOnError extends boolean = false>(
+  options: Options<SendLiveCommandData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).post<
+    SendLiveCommandResponse,
+    SendLiveCommandError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/live/{runId}/commands",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+};
+
 /**
  * Read a run's signals
  * Returns one page of the signals a run has already produced, newest-last, optionally from a
@@ -1521,8 +1578,9 @@ export const updateLiveParams = <ThrowOnError extends boolean = false>(
  * serving a shortened page that looks complete. Treat that as a normal outcome: read
  * `availableSinceMs` from the error and start again from there.
  *
- * Readable by the run's owner, and by anyone if the run is `public` — the same rule the
- * signal channel applies to a subscription.
+ * Readable by the run's owner, and by anyone if the run is `public` and has reached the `live`
+ * stage — the same rule the signal channel applies to a subscription. A `sandbox` run is read
+ * by its owner only, whatever visibility it asked for.
  *
  */
 export const getLiveRunSignals = <ThrowOnError extends boolean = false>(
@@ -1556,8 +1614,8 @@ export const getLiveRunSignals = <ThrowOnError extends boolean = false>(
  * mark`, taken every minute of market time). Until either exists the account holds its
  * starting capital.
  *
- * Readable by the run's owner, and by anyone if the run is `public`. A run started without
- * a `paper` block answers `404`.
+ * Readable by the run's owner, and by anyone if the run is `public` and has reached the `live`
+ * stage. A run started without a `paper` block answers `404`.
  *
  */
 export const getLiveRunPaper = <ThrowOnError extends boolean = false>(
@@ -1590,7 +1648,8 @@ export const getLiveRunPaper = <ThrowOnError extends boolean = false>(
  * `currency` narrows to one account; without it, every account's points come interleaved by
  * time, each carrying its currency.
  *
- * Readable by the run's owner, and by anyone if the run is `public`.
+ * Readable by the run's owner, and by anyone if the run is `public` and has reached the `live`
+ * stage.
  *
  */
 export const getLiveRunPaperEquity = <ThrowOnError extends boolean = false>(

package/src/generated/types.gen.ts

@@ -119,12 +119,34 @@ export type Account = {
    * Your current subscription tier.
    */
   tier: string;
+  /**
+   * Maximum number of strategy executions (and sweeps) you can have running at the same time
+   * through the API. Starting one past this number is answered with `429`, whose message
+   * carries the same number. The value already includes any API allowance your plan has.
+   *
+   */
+  maxExecute: number;
+  /**
+   * Maximum length, in days, of the time range of a backtest on one of your own datasets.
+   */
+  maxRangeDays: number;
+  /**
+   * Largest full grid, in parameter combinations, a sweep may run with the `grid` sampler.
+   * A grid with more combinations is refused with `400`; the `random` and `lhs` samplers run
+   * only their `samples` and are not held to it.
+   *
+   */
+  maxSweepCartesian: number;
+  /**
+   * Maximum length, in hours, of the time range of one dataset import from an exchange.
+   */
+  maxImportRangeHours: number;
   /**
    * Maximum number of active datasets your tier allows.
    */
   maxDatasets: number;
   /**
-   * Maximum size, in bytes, of a single dataset version.
+   * Maximum size, in bytes, of a single dataset version as stored, that is the `bytes` of its ready version. For a CSV upload that is the converted file, not the file you upload, so estimate from the number of rows. The Datasets guide has the details.
    */
   maxDatasetBytes: number;
   /**
@@ -512,6 +534,11 @@ export type SweepAxis =
     };
 
 export type SweepSpecRequest = {
+  /**
+   * `grid` runs every combination of the axes and is held to your plan's
+   * `maxSweepCartesian` (`GET /account`); `random` and `lhs` run `samples` combinations and are not.
+   *
+   */
   sampler?: "grid" | "random" | "lhs";
   /**
    * Reproducibility seed. If omitted, the server generates one with Java's
@@ -1208,6 +1235,12 @@ export type StrategySummary = {
    *
    */
   requiredSources?: Array<string>;
+  /**
+   * When you deleted this strategy. Only ever present in `GET /strategies?includeDeleted=true`,
+   * and only on strategies you have deleted.
+   *
+   */
+  deletedAt?: string;
 };
 
 /**
@@ -1321,6 +1354,12 @@ export type Dataset = {
    *
    */
   currentVersionId?: string;
+  /**
+   * When you deleted this dataset. Only ever present in `GET /datasets?includeDeleted=true`,
+   * and only on datasets you have deleted.
+   *
+   */
+  deletedAt?: string;
   /**
    * When `currentVersionId` last changed. Absent until it has a value.
    */
@@ -1775,11 +1814,11 @@ export type StartLiveRequest = {
     [key: string]: unknown;
   };
   /**
-   * A `public` run appears in `GET /live/public` and its signal channel accepts subscriptions from anyone, not only you.
+   * A `public` run appears in `GET /live/public` and its signal channel accepts subscriptions from anyone, not only you — from the moment it is promoted to `live`. While it is a `sandbox` trial, `public` is only what you asked for, and only you can read it.
    */
   visibility?: "private" | "public";
   /**
-   * Request that this run's signals be relayed over its WebSocket channel once it reaches the `live` stage — see the "Live execution" guide. Has no effect while the run is still in the `sandbox` stage, regardless of this value.
+   * 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;
   name?: string;
@@ -1842,6 +1881,19 @@ export type UpdateLiveParamsRequest = {
   };
 };
 
+export type SendLiveCommandRequest = {
+  /**
+   * The command's text — non-blank.
+   */
+  command: string;
+  /**
+   * An optional map of your own choosing, alongside command. Absent means none; when given, it must be a JSON object, and `command` and `properties` are the only keys the body may carry. Each entry lands as a top-level entry on the strategy's `CommandRequest` — no key is off limits, since the command's own text is kept separately.
+   */
+  properties?: {
+    [key: string]: unknown;
+  };
+};
+
 /**
  * A live run's full state, as returned by starting, reading, or stopping it through its strategy.
  */
@@ -1855,11 +1907,11 @@ export type LiveRun = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX` — a trial run compared against a second execution for agreement — and moves to `LIVE` once it passes.
+   * A new run always starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up.
    */
   stage: "SANDBOX" | "LIVE";
   /**
-   * `STARTING` until first observed running; otherwise the runner's own reported state (e.g. `RUNNING`).
+   * The run's health right now: `STARTING` (no runner has reported on it yet), `RUNNING`, `LAGGING` (behind the market data, usually while catching up; clears by itself), `HUNG` (stuck inside one strategy call for longer than allowed; clears when it returns), `DEGRADED` (its independent executions produced different signals), `FAILED` (refused, could not start or failed while running; `reason` says why) or `STOPPED`. `LAGGING`, `HUNG` and `DEGRADED` come and go on a running run. The set may grow: read an unknown value as a running run with something to look at. See the Live execution guide.
    */
   state: string;
   /**
@@ -1867,7 +1919,17 @@ export type LiveRun = {
    */
   desired: "RUNNING" | "STOPPED";
   /**
-   * Present only when the run stopped because it exceeded its resource allowance.
+   * Why the run stopped or failed, when there is something to say; absent otherwise. It is never a
+   * stack trace or an internal message. Either `resource: ...` (the platform stopped the run for
+   * exceeding its resource allowance; the text says which limit) or one of a fixed set of sentences for
+   * a `FAILED` run: the strategy cannot consume the source type the run was started with, the run's
+   * definition was refused, the run could not start after several attempts, the strategy failed while
+   * processing data, the run lost its data feed, or the generic `The run failed.`. The set may grow:
+   * read an unrecognised sentence as a failure and do not parse it. A `FAILED` run usually stays
+   * `desired: RUNNING` until you stop it, and counts as active (`409` on a new start, and toward your
+   * live-run limit) until then; one that can never run because its strategy cannot consume its source
+   * type is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
+   *
    */
   reason?: string;
   sources: Array<LiveSource>;
@@ -1879,7 +1941,7 @@ export type LiveRun = {
    */
   paramsVersion: number;
   /**
-   * Whether this run's signals are being relayed over the WebSocket channel described in the "Live execution" guide, right now. This is the effective value — `false` on a `sandbox` run regardless of what was requested at start; matches the requested value once `stage` reaches `live`.
+   * Whether this run's signals are relayed over the WebSocket channel described in the "Live execution" guide. It is the value requested at start, in either stage.
    */
   relay: boolean;
   /**
@@ -1887,7 +1949,7 @@ export type LiveRun = {
    */
   startedAtMs: number;
   /**
-   * The sandbox trial's promotion verdict, once one exists. Shape is not yet stabilized as public API — treat as opaque diagnostics.
+   * The sandbox trial's promotion verdict. Absent for the whole 24-hour trial and present once it ends, so an absent `gate` means the trial has not finished. `passed` is the verdict; the rest is diagnostic detail whose shape is not yet stabilized as public API: treat it as opaque.
    */
   gate?: {
     [key: string]: unknown;
@@ -1924,17 +1986,31 @@ export type LiveRunSummary = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX` — a trial run compared against a second execution for agreement — and moves to `LIVE` once it passes.
+   * A new run always starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up.
    */
   stage: "SANDBOX" | "LIVE";
   /**
-   * `STARTING` until first observed running; otherwise the runner's own reported state (e.g. `RUNNING`).
+   * The run's health right now: `STARTING` (no runner has reported on it yet), `RUNNING`, `LAGGING` (behind the market data, usually while catching up; clears by itself), `HUNG` (stuck inside one strategy call for longer than allowed; clears when it returns), `DEGRADED` (its independent executions produced different signals), `FAILED` (refused, could not start or failed while running; `reason` says why) or `STOPPED`. `LAGGING`, `HUNG` and `DEGRADED` come and go on a running run. The set may grow: read an unknown value as a running run with something to look at. See the Live execution guide.
    */
   state: string;
   /**
    * What you last asked for. `state` can lag this briefly after `DELETE`.
    */
   desired: "RUNNING" | "STOPPED";
+  /**
+   * Why the run stopped or failed, when there is something to say; absent otherwise. It is never a
+   * stack trace or an internal message. Either `resource: ...` (the platform stopped the run for
+   * exceeding its resource allowance; the text says which limit) or one of a fixed set of sentences for
+   * a `FAILED` run: the strategy cannot consume the source type the run was started with, the run's
+   * definition was refused, the run could not start after several attempts, the strategy failed while
+   * processing data, the run lost its data feed, or the generic `The run failed.`. The set may grow:
+   * read an unrecognised sentence as a failure and do not parse it. A `FAILED` run usually stays
+   * `desired: RUNNING` until you stop it, and counts as active (`409` on a new start, and toward your
+   * live-run limit) until then; one that can never run because its strategy cannot consume its source
+   * type is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
+   *
+   */
+  reason?: string;
   sources: Array<LiveSource>;
   /**
    * Epoch milliseconds this run was started.
@@ -2140,7 +2216,7 @@ export type LiveSignal = {
   instrument: LiveSignalInstrument | null;
   order?: LiveSignalOrder;
   /**
-   * The signal's own free-form payload.
+   * The signal's own free-form payload, what the strategy put there with `signal.set(...)`. Whoever may read the run may read it, so on a `public` run it is public. A signal whose `data` is over 8 KiB (8,192 bytes of its JSON) is not pushed on the WebSocket channel, and `GET /live/{runId}/signals` returns it whole.
    */
   data?: {
     [key: string]: unknown;
@@ -2192,6 +2268,18 @@ export type LiveParamsUpdateResult = {
   effectiveAtMs: number;
 };
 
+export type LiveCommandResult = {
+  runId: string;
+  /**
+   * This command's own id, generated fresh for this call. A retried request is a second, distinct command — this endpoint takes no idempotency key.
+   */
+  commandId: string;
+  /**
+   * Epoch milliseconds — the market position every execution applies this command at.
+   */
+  effectiveAtMs: number;
+};
+
 export type AuthenticateData = {
   body?: never;
   path?: never;
@@ -2473,7 +2561,14 @@ export type DownloadKlinesResponse =
 export type ListStrategiesData = {
   body?: never;
   path?: never;
-  query?: never;
+  query?: {
+    /**
+     * `true` also lists the strategies you have deleted, each with its `deletedAt`. Any other
+     * value, or leaving it out, lists only the ones you have not deleted.
+     *
+     */
+    includeDeleted?: boolean;
+  };
   url: "/strategies";
 };
 
@@ -2508,6 +2603,10 @@ export type CompileStrategyErrors = {
    *
    */
   400: ResponseError;
+  /**
+   * The source is larger than 32 KiB (32768 bytes). Every endpoint that reads a request body caps it, and the message names the cap; see the Strategy guide.
+   */
+  413: ResponseError;
   /**
    * Too many compilations in flight. Retry later.
    */
@@ -2807,7 +2906,9 @@ export type ExecuteSweepData = {
 export type ExecuteSweepErrors = {
   /**
    * Invalid sweep specification, a `type` that cannot be swept yet (`funding`), or the
-   * expanded grid exceeds the server limit.
+   * expanded grid exceeds the server limit. A full `grid` with more combinations than your
+   * plan allows (`maxSweepCartesian` in `GET /account`) is refused with a message that asks
+   * for the `random` or `lhs` sampler.
    *
    */
   400: ResponseError;
@@ -3202,7 +3303,14 @@ export type GetBacktestResultResponse =
 export type ListDatasetsData = {
   body?: never;
   path?: never;
-  query?: never;
+  query?: {
+    /**
+     * `true` also lists the datasets you have deleted, each with its `deletedAt`. Any other
+     * value, or leaving it out, lists only the ones you have not deleted.
+     *
+     */
+    includeDeleted?: boolean;
+  };
   url: "/datasets";
 };
 
@@ -3388,7 +3496,7 @@ export type FinalizeDatasetUploadErrors = {
    */
   409: ResponseError;
   /**
-   * The uploaded file exceeds your tier's size limit for a dataset.
+   * The uploaded file is many times your tier's size limit for a dataset. The limit itself applies to the stored size, which is known only after conversion, so an upload that passes here can still end `failed` when ingest finishes.
    */
   413: ResponseError;
   /**
@@ -3611,7 +3719,7 @@ export type StartLiveData = {
 
 export type StartLiveErrors = {
   /**
-   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), 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.
    */
   400: ResponseError;
   /**
@@ -3765,7 +3873,7 @@ export type UpdateLiveParamsErrors = {
    */
   404: ResponseError;
   /**
-   * This run's compilation has no declared properties on record — recompile the strategy to enable runtime parameter updates.
+   * This run's compiled strategy has no record of the parameters it declares. Register the strategy again with `POST /strategy` and start a new run, since a run keeps the compiled version it started with.
    */
   409: ResponseError;
 };
@@ -3783,6 +3891,55 @@ export type UpdateLiveParamsResponses = {
 export type UpdateLiveParamsResponse =
   UpdateLiveParamsResponses[keyof UpdateLiveParamsResponses];
 
+export type SendLiveCommandData = {
+  body: SendLiveCommandRequest;
+  path: {
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}/commands";
+};
+
+export type SendLiveCommandErrors = {
+  /**
+   * `command` missing, not a string, blank; `properties` given but not an object; or the body carries any key other than `command` and `properties`.
+   */
+  400: ResponseError;
+  /**
+   * No such run, or you do not own it.
+   */
+  404: ResponseError;
+  /**
+   * One of three reasons, each its own message: the run is not running, so there is nothing to tell;
+   * this run's compiled strategy has no record of whether it handles commands — register the strategy
+   * again with `POST /strategy` and start a new run, since a run keeps the compiled version it started
+   * with; or the strategy does not implement `CommandRequestHandler` at all.
+   *
+   */
+  409: ResponseError;
+  /**
+   * The request body is larger than 2 KiB (2048 bytes). Every endpoint that reads a request body caps it, and the message names the cap.
+   */
+  413: ResponseError;
+  /**
+   * The command could not be delivered right now, and it was not sent — unlike a parameter update, a command has no fallback path. Try again.
+   */
+  503: ResponseError;
+};
+
+export type SendLiveCommandError =
+  SendLiveCommandErrors[keyof SendLiveCommandErrors];
+
+export type SendLiveCommandResponses = {
+  /**
+   * Accepted — on its way to every execution behind the run.
+   */
+  202: LiveCommandResult;
+};
+
+export type SendLiveCommandResponse =
+  SendLiveCommandResponses[keyof SendLiveCommandResponses];
+
 export type GetLiveRunSignalsData = {
   body?: never;
   path: {