@qtsurfer/api-client 0.11.0 → 0.13.0

package/src/generated/schemas.gen.ts

@@ -705,9 +705,76 @@ export const ExecuteSweepRequestSchema = {
     walkForward: {
       $ref: "#/components/schemas/WalkForwardRequest",
     },
+    equityCurve: {
+      $ref: "#/components/schemas/EquityCurveRequest",
+    },
   },
 } as const;
 
+export const EquityCurveOptionsSchema = {
+  type: "object",
+  description:
+    "Requested equity-curve transform, applied server-side in a fixed pipeline order: `resample` (point count) then `differential` (encoding) then `outMode` (JSON shape) — each stage assumes the previous one already ran. A server-side size guard can still force a smaller/deflated shape above its thresholds regardless of what is requested here — see `EquityCurveMeta` for what actually happened.",
+  properties: {
+    resample: {
+      type: "integer",
+      minimum: 2,
+      description:
+        "Downsample to at most this many points (extrema-preserving — the global max/min and the exact first/last point are always kept). Omit for no downsampling.",
+    },
+    differential: {
+      type: "boolean",
+      default: false,
+      description:
+        "Delta-encode both fields from the second (post-resample) point onward.",
+    },
+    outMode: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/EquityCurveOutMode",
+        },
+      ],
+      default: "ARRAY",
+      description: "Requested JSON shape.",
+    },
+  },
+} as const;
+
+export const EquityCurveRequestSchema = {
+  allOf: [
+    {
+      $ref: "#/components/schemas/EquityCurveOptions",
+    },
+    {
+      type: "object",
+      properties: {
+        mode: {
+          type: "string",
+          enum: ["auto", "topN", "topPct", "none"],
+          default: "auto",
+          description:
+            "Which trials keep their per-point equity curve. `auto` retains curves only while the accumulated size stays within server limits; `topN`/`topPct` retain curves for the best-ranked trials explicitly; `none` retains no curves.",
+        },
+        n: {
+          type: "integer",
+          minimum: 1,
+          description: "Trial count to retain when mode is topN.",
+        },
+        maxPct: {
+          type: "number",
+          format: "double",
+          exclusiveMinimum: 0,
+          maximum: 100,
+          description:
+            "Top percentage of trials to retain when mode is topPct.",
+        },
+      },
+    },
+  ],
+  description:
+    "Selection (`mode`/`n`/`maxPct`) plus the transform preference (`resample`/`differential`/`outMode`) applied by `GET .../equityCurve` whenever ITS OWN query params are absent, for a curve this sweep retained. The transform half never affects retention or `sweepId` — a caller can always override it per-request at read time regardless of what was submitted here.",
+} as const;
+
 export const WalkForwardRequestSchema = {
   type: "object",
   description:
@@ -949,6 +1016,15 @@ export const SweepRunRowSchema = {
       type: "integer",
       format: "int64",
     },
+    equityCurve: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/EquityCurveResult",
+        },
+      ],
+      description:
+        "Present only when this trial's curve was selected (`equityCurve.mode` was `topN`/`topPct` on the request, and this row ranked among the winners) — absent, not null, otherwise; a run that was never spilled and one that was spilled but not selected look identical here. Always a pointer today (`url` present, no inline points): a sweep's curves live in a spill store, not the response, until fetched separately. `GET` the `url` to fetch the curve itself; its own `meta` there is the real, possibly size-guarded outcome, while this outer `meta` is a raw, untransformed preview from selection time and can differ.",
+    },
   },
 } as const;
 
@@ -1086,6 +1162,7 @@ export const ExecuteSweepResultSchema = {
     "leaderboardSize",
     "truncated",
     "leaderboard",
+    "state",
   ],
   properties: {
     sweepId: {
@@ -1094,6 +1171,8 @@ export const ExecuteSweepResultSchema = {
     status: {
       type: "string",
       enum: ["RUNNING", "COMPLETED", "PARTIAL", "CANCELLED"],
+      description:
+        "The sweep's own status vocabulary — not the same set `state.status` below uses. See `state` for why.",
     },
     objective: {
       type: "string",
@@ -1148,6 +1227,17 @@ First failure wins and later ones are not recorded, so on a sweep where several
     walkForward: {
       $ref: "#/components/schemas/WalkForwardResult",
     },
+    state: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/JobState",
+        },
+      ],
+      description: `The same \`JobState\` shape a single-execute \`BacktestJobResult\` carries — not a sweep-specific lookalike, the actual type, so field names and timestamp formatting match exactly.
+\`state.status\` uses \`JobState\`'s own vocabulary (\`New\`/\`Started\`/\`Completed\`/ \`Aborted\`/\`Failed\`), mapped from the sweep's \`status\` field above rather than copying it: \`PARTIAL\` and \`CANCELLED\` both map to \`Aborted\`, because a sweep's \`PARTIAL\` is already terminal (some shards finished, some failed, nothing more is coming) unlike a single job's non-terminal \`Partial\`, which has no equivalent here at all.
+\`state.completed\` is real ticks processed on a plain sweep. On a \`walkForward\` sweep it is currently always \`0\` — the walk-forward fold runner was not wired to count ticks when this shipped, unlike the plain shard path.
+\`state.size\` is always \`0\` on every path (single execute, plain sweep, walk-forward alike) — nothing populates it anywhere yet. That is a known gap across the whole API, not a sweep-specific omission.`,
+    },
   },
 } as const;
 
@@ -1389,26 +1479,36 @@ reading: a run that produced no trades often did so for a reason stated here.
       example: 8.75,
     },
     equityCurve: {
-      type: "array",
-      description:
-        "Equity curve over the backtest. Element 0 is an anchor at the backtest `from` with `initialCapital`; the remaining points are one sample per emitted yield, in order. Use it to plot the strategy's running equity without re-deriving it from the yield history.",
-      items: {
-        $ref: "#/components/schemas/EquityPoint",
-      },
-      example: [
-        {
-          timestamp: 1700000000000,
-          equity: 100,
-        },
-        {
-          timestamp: 1700000060000,
-          equity: 110.5,
-        },
+      allOf: [
         {
-          timestamp: 1700000120000,
-          equity: 90.25,
+          $ref: "#/components/schemas/EquityCurveResult",
         },
       ],
+      description:
+        "Equity curve over the backtest. `points[0]` (or `timestamps[0]`/`equities[0]` in `SHORT` mode) is an anchor at the backtest `from` with `initialCapital`; the remaining points are one sample per emitted yield, in order. Use it to plot the strategy's running equity without re-deriving it from the yield history. Always inline for a plain backtest today — never a pointer (`url`); that shape exists only for a sweep row's top-N winners.",
+      example: {
+        points: [
+          {
+            timestamp: 1700000000000,
+            equity: 100,
+          },
+          {
+            timestamp: 1700000060000,
+            equity: 110.5,
+          },
+          {
+            timestamp: 1700000120000,
+            equity: 90.25,
+          },
+        ],
+        meta: {
+          inputPointCount: 3,
+          outputPointCount: 3,
+          resampled: false,
+          differential: false,
+          outMode: "ARRAY",
+        },
+      },
     },
     signalCount: {
       type: "integer",
@@ -1475,6 +1575,104 @@ export const EquityPointSchema = {
   },
 } as const;
 
+export const EquityCurveOutModeSchema = {
+  type: "string",
+  enum: ["ARRAY", "SHORT"],
+  description:
+    "JSON shape for an equity curve's points. `ARRAY` is `[{timestamp, equity}, ...]`; `SHORT` is `{timestamps: [...], equities: [...]}` (parallel arrays, no repeated key text). The one schema shared by every place `outMode` appears, request or response, so the two cannot drift to different value sets.",
+} as const;
+
+export const EquityCurveMetaSchema = {
+  type: "object",
+  description:
+    "What the transform pipeline actually did, computed from the observed outcome — never a copy of what was requested. Lets a caller detect a forced or no-op transform (e.g. a `resample` ceiling already above the curve's size is a legal no-op, reported honestly as `resampled: false`).",
+  required: [
+    "inputPointCount",
+    "outputPointCount",
+    "resampled",
+    "differential",
+    "outMode",
+  ],
+  properties: {
+    inputPointCount: {
+      type: "integer",
+      description: "Size of the curve the transform pipeline received.",
+      example: 100000,
+    },
+    outputPointCount: {
+      type: "integer",
+      description:
+        "Size after the full pipeline (resample, then differential, then outMode).",
+      example: 100,
+    },
+    resampled: {
+      type: "boolean",
+      description:
+        "True only if the resample stage actually changed the point count.",
+    },
+    differential: {
+      type: "boolean",
+      description:
+        "True only if delta-encoding actually ran. Requesting it on a curve of 0 or 1 points has nothing to encode, so it does not run even if asked.",
+    },
+    outMode: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/EquityCurveOutMode",
+        },
+      ],
+      description:
+        "The actual JSON shape served. Present even when the points themselves are not (a pointer curve, `EquityCurveResult.url`) — a caller resolving that URL separately still needs to know how to parse what it gets back before fetching it. May override an explicit request above a server-side size threshold; this field, not the request, is the source of truth for what shape actually came back.",
+      example: "ARRAY",
+    },
+  },
+} as const;
+
+export const EquityCurveResultSchema = {
+  type: "object",
+  description:
+    "An equity curve, shaped per `meta.outMode`: `points` when `ARRAY`, `timestamps` + `equities` (parallel arrays) when `SHORT`. Used identically wherever a curve is returned — a plain backtest's inline `equityCurve` and a sweep row's `equityCurve` are the same type. `url` is present *instead of* any points when the curve is served by pointer rather than inline (a sweep row's top-N winners only): `GET` it separately to fetch this exact same shape with the points populated.",
+  required: ["meta"],
+  properties: {
+    meta: {
+      $ref: "#/components/schemas/EquityCurveMeta",
+    },
+    points: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `ARRAY` and the curve is inline (not a pointer).",
+      items: {
+        $ref: "#/components/schemas/EquityPoint",
+      },
+    },
+    timestamps: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `SHORT` and the curve is inline (not a pointer).",
+      items: {
+        type: "integer",
+        format: "int64",
+      },
+    },
+    equities: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `SHORT` and the curve is inline (not a pointer), parallel to `timestamps` (same index, same point).",
+      items: {
+        type: "number",
+        format: "double",
+      },
+    },
+    url: {
+      type: "string",
+      description:
+        "Present only for a sweep row's pointer curve. `GET` this to fetch the curve itself, in this exact `{points|timestamps+equities, meta}` shape — `meta` there is the real, possibly size-guarded outcome; this outer `meta` is a raw, untransformed preview from the moment the sweep selected this trial's curve, and the two can legitimately differ.",
+      example:
+        "/v1/backtest/binance/ticker/executeSweep/req-1/swp_test/runs/3/equityCurve",
+    },
+  },
+} as const;
+
 export const strategyIdSchema = {
   description: `Unique identifier for a compiled strategy, derived from the source itself: the same code
 always yields the same id, for every caller, whatever its formatting. See
@@ -1484,6 +1682,68 @@ always yields the same id, for every caller, whatever its formatting. See
   example: "6bsh31ikwkuivhtgcoa6s4",
 } as const;
 
+export const DeclaredPropertySchema = {
+  type: "object",
+  description: `One property name \`POST /strategy\` could establish without constructing the strategy —
+either declared with \`@StrategyProperty\` on the compiled source, or one of the small set of
+base properties every strategy carries (\`amnt\`, \`enabled\`, \`multiEntry\`, ...).
+
+**Best-effort, not exhaustive.** A property registered through an attached risk/backtest
+config needs a live instance to discover and is not listed here. Use this to catch a typo'd
+sweep key before submitting, not as the definitive list of what a sweep will accept — a
+name absent from this list may still be valid.
+`,
+  required: ["name"],
+  properties: {
+    name: {
+      type: "string",
+      description:
+        "The key a sweep or execute param map uses for this property.",
+      example: "rsi.period",
+    },
+    description: {
+      type: "string",
+      description: "Human-readable label, as declared.",
+      example: "RSI period",
+    },
+    defaultValue: {
+      type: "string",
+      description: `The declared default, as a string, if one was given. Absent, not null, when none was
+declared.
+`,
+      example: "14",
+    },
+    reflected: {
+      type: "boolean",
+      description: `Whether a value for this key is injected into the strategy's field (\`true\`) or only
+available through the property map (\`false\`).
+`,
+      example: true,
+    },
+    min: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range minimum, if declared. Advisory only, never validated.",
+      example: 2,
+    },
+    max: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range maximum, if declared. Advisory only, never validated.",
+      example: 50,
+    },
+    step: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range step, if declared. Advisory only, never validated.",
+      example: 1,
+    },
+  },
+} as const;
+
 export const NoticeSchema = {
   type: "object",
   description: `A diagnostic the engine raised while the strategy ran. Advisory: it describes something worth
@@ -1767,52 +2027,91 @@ export const DatasetWithLinksSchema = {
   ],
 } as const;
 
+export const DatasetUploadTargetSchema = {
+  description:
+    "A presigned destination for uploading a raw dataset file directly to storage.",
+  type: "object",
+  required: ["url", "expiresInMinutes"],
+  properties: {
+    url: {
+      type: "string",
+      description: `Presigned URL. \`PUT\` the raw CSV file here directly — no \`Authorization\` header,
+no other API credentials.
+`,
+      example:
+        "https://storage.qtsurfer.com/uploads/00000000-.../up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
+    },
+    expiresInMinutes: {
+      type: "integer",
+      description: "How long `url` stays valid.",
+      example: 15,
+    },
+  },
+} as const;
+
+export const DatasetUploadSessionSchema = {
+  description: `An upload session — an id plus the presigned URL to PUT the raw file to. Returned both by
+\`POST /datasets\` (as part of the new dataset) and by \`POST /datasets/{datasetId}/uploads\`
+(on its own, for an existing one).
+`,
+  type: "object",
+  required: ["uploadId", "upload"],
+  properties: {
+    uploadId: {
+      type: "string",
+      description: `Identifies this upload session. Pass to
+\`POST /datasets/{datasetId}/uploads/{uploadId}/finalize\` once the PUT completes.
+`,
+      example: "up_1a2b3c4d5e6f7a8b",
+    },
+    upload: {
+      $ref: "#/components/schemas/DatasetUploadTarget",
+    },
+  },
+} as const;
+
 export const DatasetCreatedSchema = {
-  description: `A \`Dataset\` plus the first upload session — the presigned URL to PUT the file to.
+  description: `The metadata available immediately after creating a dataset, plus its first upload
+session — the presigned URL to PUT the file to. Version-derived fields such as
+\`createdAt\`, \`currentVersionId\`, range, and cadence are available from \`GET /datasets/{datasetId}\`
+after the relevant lifecycle stages, not in this creation response.
 `,
   allOf: [
-    {
-      $ref: "#/components/schemas/Dataset",
-    },
     {
       type: "object",
-      required: ["uploadId", "upload"],
+      required: ["datasetId", "name", "type", "instrument"],
       properties: {
-        uploadId: {
+        datasetId: {
           type: "string",
-          description: `Identifies this upload session. Pass to
-\`POST /datasets/{datasetId}/uploads/{uploadId}/finalize\` once the PUT completes.
-`,
-          example: "up_1a2b3c4d5e6f7a8b",
+          description: "Opaque id of the newly created dataset.",
+          example: "ds_3f9a1c2e7b0d4a5f",
         },
-        upload: {
-          type: "object",
-          required: ["url", "expiresInMinutes"],
-          properties: {
-            url: {
-              type: "string",
-              description: `Presigned URL. \`PUT\` the raw CSV file here directly — no \`Authorization\`
-header, no other API credentials.
-`,
-              example:
-                "https://storage.qtsurfer.com/00000000-.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
-            },
-            expiresInMinutes: {
-              type: "integer",
-              description: "How long `url` stays valid.",
-              example: 15,
-            },
-          },
+        name: {
+          type: "string",
+          description: "Unique name of the newly created dataset.",
+          example: "My BTC ticks",
+        },
+        type: {
+          type: "string",
+          enum: ["ticker"],
+          description: "Always `ticker` in v1.",
+          example: "ticker",
+        },
+        instrument: {
+          $ref: "#/components/schemas/Instrument",
         },
       },
     },
+    {
+      $ref: "#/components/schemas/DatasetUploadSession",
+    },
   ],
 } as const;
 
 export const DatasetVersionSchema = {
   type: "object",
   description: `One successfully ingested upload. Cadence and timestamp unit are discovered from the file,
-not declared by the caller (D-11).
+not declared by the caller.
 `,
   required: ["datasetId"],
   properties: {

package/src/generated/sdk.gen.ts

@@ -58,6 +58,9 @@ import type {
   GetSweepSensitivityData,
   GetSweepSensitivityResponse,
   GetSweepSensitivityError,
+  GetSweepRunEquityCurveData,
+  GetSweepRunEquityCurveResponse,
+  GetSweepRunEquityCurveError,
   ExecuteBacktestData,
   ExecuteBacktestResponse,
   ExecuteBacktestError,
@@ -78,6 +81,9 @@ import type {
   GetDatasetData,
   GetDatasetResponse,
   GetDatasetError,
+  OpenDatasetUploadData,
+  OpenDatasetUploadResponse,
+  OpenDatasetUploadError,
   FinalizeDatasetUploadData,
   FinalizeDatasetUploadResponse,
   FinalizeDatasetUploadError,
@@ -316,6 +322,10 @@ export const listStrategies = <ThrowOnError extends boolean = false>(
  * different means are two strategies, because deciding otherwise would mean deciding program
  * equivalence.
  *
+ * The response also lists `declaredProperties` — the sweep/execute param keys this strategy
+ * is known to accept, so a caller can catch a typo'd key before submitting a sweep instead of
+ * only learning it from a rejected one. See `DeclaredProperty`: best-effort, not exhaustive.
+ *
  */
 export const compileStrategy = <ThrowOnError extends boolean = false>(
   options: Options<CompileStrategyData, ThrowOnError>
@@ -689,6 +699,41 @@ export const getSweepSensitivity = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * Get one sweep trial's equity curve
+ * The resource a leaderboard row's `equityCurve.url` points at — only reachable when that
+ * trial's curve was actually selected (`equityCurve.mode: topN` or `topPct` on the sweep
+ * submission, and this trial ranked among the winners). Returns the exact same
+ * `{points|timestamps+equities, meta}` shape a plain backtest's inline `equityCurve` carries.
+ *
+ * Query params reshape the response the same way a plain backtest's `equityCurve` options do.
+ * A param genuinely absent from the query string falls back to the `equityCurve` transform
+ * preference the sweep was submitted with — a param
+ * present but malformed does not fall back, it degrades the same way it always has. Above a
+ * server-side size threshold, the shape is forced regardless of either — `meta.outMode` in
+ * the response, not the query string or the submitted default, is the source of truth for
+ * what shape actually came back.
+ *
+ */
+export const getSweepRunEquityCurve = <ThrowOnError extends boolean = false>(
+  options: Options<GetSweepRunEquityCurveData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).get<
+    GetSweepRunEquityCurveResponse,
+    GetSweepRunEquityCurveError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}/runs/{runIx}/equityCurve",
+    ...options,
+  });
+};
+
 /**
  * Execute a compiled strategy against a prepared dataset
  * Enqueues an execute task that runs the strategy identified by `strategyId` over the data
@@ -698,8 +743,9 @@ export const getSweepSensitivity = <ThrowOnError extends boolean = false>(
  * Returns immediately with a `jobId`; poll `GET /backtest/{exchangeId}/{type}/execute/{jobId}`
  * for the result.
  *
- * The same params (same `prepareJobId`, `strategyId`, `storeSignals`) always return the same
- * `jobId` (idempotent).
+ * The same params (same `prepareJobId`, `strategyId`, `storeSignals`, `equityCurve`) always
+ * return the same `jobId` (idempotent) — a request that omits `equityCurve` dedupes exactly
+ * as it did before that field existed.
  *
  * Works unchanged for a dataset-backed prepare (`exchangeId: user`) — the request body is
  * identical either way, since the instrument and range are recovered from `prepareJobId`.
@@ -816,6 +862,10 @@ export const listDatasets = <ThrowOnError extends boolean = false>(
  * `POST /datasets/{datasetId}/uploads/{uploadId}/finalize` once the upload completes to kick
  * off ingest.
  *
+ * Losing this response loses nothing: calling this dataset's
+ * `POST /datasets/{datasetId}/uploads` returns the very same upload session again rather than
+ * opening a new one, as long as nothing has been finalized against it yet.
+ *
  * v1 is ticker data only — `type` is not a request field, it is always `"ticker"` in the
  * response. `instrument` must be a plain spot pair (`BASE/QUOTE`, exactly one `/`); derivative
  * forms (e.g. `BTC/USDT:USDT`) are rejected.
@@ -899,14 +949,48 @@ export const getDataset = <ThrowOnError extends boolean = false>(
   });
 };
 
+/**
+ * Open a new upload session for an existing dataset
+ * Get a fresh presigned URL to upload a new version into a dataset you already have — a
+ * corrected file, or the next chunk of history. Behaves the same way `POST /datasets` does
+ * for a brand-new dataset's own upload: at most one upload session is open per dataset at a
+ * time, so calling this again before finalizing just hands back that same session rather
+ * than opening a second one — safe to call repeatedly if a response gets lost.
+ *
+ * Once a session has been finalized (successfully or not), the next call here opens a
+ * genuinely new one for that dataset's next version.
+ *
+ */
+export const openDatasetUpload = <ThrowOnError extends boolean = false>(
+  options: Options<OpenDatasetUploadData, ThrowOnError>
+) => {
+  return (options.client ?? _heyApiClient).post<
+    OpenDatasetUploadResponse,
+    OpenDatasetUploadError,
+    ThrowOnError
+  >({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http",
+      },
+    ],
+    url: "/datasets/{datasetId}/uploads",
+    ...options,
+  });
+};
+
 /**
  * Finalize an uploaded file and start ingest
- * Call once the file has been PUT to the `upload.url` from `POST /datasets`. Enqueues ingest
- * and returns immediately; poll
+ * Call once the file has been PUT to the `upload.url` from `POST /datasets` (or from
+ * `POST /datasets/{datasetId}/uploads`). Enqueues ingest and returns immediately; poll
  * `GET /datasets/{datasetId}/uploads/{uploadId}` for the result.
  *
- * Idempotent — a repeat finalize of the same upload returns the same `jobId` rather than
- * enqueueing a second ingest.
+ * Idempotent while the upload is still open — a repeat finalize before it has produced a
+ * version returns the same `jobId` rather than enqueueing a second ingest. Once it HAS
+ * produced a version, `uploadId` is spent: finalizing it again is a `409`, even with
+ * different bytes freshly PUT to the same URL — open a new upload session instead
+ * (`POST /datasets/{datasetId}/uploads`) rather than reusing a spent one.
  *
  */
 export const finalizeDatasetUpload = <ThrowOnError extends boolean = false>(