@qtsurfer/sdk 0.7.0 → 0.8.0

package/src/client.ts

@@ -5,11 +5,30 @@ import {
   type BacktestRequest,
   type BacktestResult,
 } from './workflows/backtest';
+import {
+  listExchanges,
+  listInstruments,
+  type Exchange,
+  type InstrumentDetail,
+  type InstrumentSegment,
+} from './workflows/catalog';
 import {
   downloadKlines,
   downloadTickers,
   type DownloadFormat,
 } from './workflows/downloads';
+import {
+  getStrategy,
+  validateStrategy as runValidateStrategy,
+  type StrategyState,
+  type StrategyValidation,
+} from './workflows/strategies';
+import {
+  sweep as runSweep,
+  type Sweep,
+  type SweepOptions,
+  type SweepRequest,
+} from './workflows/sweep';
 
 /** Configuration for {@link QTSurfer}. */
 export interface QTSurferOptions {
@@ -41,7 +60,9 @@ export interface DownloadHourArgs {
 
 /**
  * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's
- * workflow methods (`backtest`, `tickers`, `klines`). Constructing an
+ * workflow methods (`backtest`, `sweep`, `tickers`, `klines`), the platform catalog
+ * (`exchanges`, `instruments`) and the strategy surface (`validateStrategy`,
+ * `strategy`). Constructing an
  * instance reconfigures the underlying api-client singleton, so avoid
  * holding two `QTSurfer`s with different `baseUrl`s or tokens alive in the
  * same process — they will race. Prefer the `authenticate()` helper over
@@ -68,6 +89,48 @@ export class QTSurfer {
     return backtest(req, opts);
   }
 
+  /**
+   * Run the full compile → prepare → executeSweep pipeline and resolve once the
+   * platform has accepted the sweep, handing back a {@link Sweep} that keeps
+   * polling the leaderboard in the background.
+   *
+   * The whole sweep is one call because the execute-sweep endpoint is addressed
+   * by the id of an already-prepared dataset: exposing the stages separately
+   * would hand dataset lifecycle to the caller and buy nothing. Preparing is
+   * idempotent, so sweeping the same window twice prepares it once.
+   *
+   * The returned promise rejects with {@link QTSStrategyCompileError} if
+   * compilation fails, {@link QTSPreparationError} if data preparation fails,
+   * {@link QTSExecutionError} if the platform rejects the sweep — an expanded
+   * grid over the server limit, or a walk-forward request whose fold count
+   * multiplies past the sweep budget, both answer `400` — {@link QTSTimeoutError}
+   * if a stage exceeds `timeoutMs`, or {@link QTSCanceledError} if the caller's
+   * signal fires before the sweep is accepted. A plain {@link QTSError} means
+   * the request itself is malformed (an empty grid, a non-positive `step`, a
+   * walk-forward block with fewer than two folds) and never reached the network.
+   *
+   * What the sweep *found* arrives through {@link Sweep.result}, which is also
+   * where the semantics of the leaderboard are documented. Acceptance already
+   * answers three things worth reading before any result exists — the effective
+   * seed, whether this submission enqueued anything, and whether this is a
+   * walk-forward sweep — see {@link Sweep.accepted}.
+   *
+   * ```ts
+   * const handle = await qts.sweep({
+   *   strategy: source,
+   *   exchangeId: 'binance',
+   *   instrument: 'BTC/USDT',
+   *   from: '2026-01-01T00:00:00Z',
+   *   to: '2026-02-01T00:00:00Z',
+   *   params: { rsiPeriod: { from: 7, to: 28, step: 1 } },
+   * });
+   * const leaderboard = await handle.result;
+   * ```
+   */
+  sweep(req: SweepRequest, opts?: SweepOptions): Promise<Sweep> {
+    return runSweep(req, opts);
+  }
+
   /**
    * Download one hour of raw tickers for an instrument as a {@link Blob}.
    * Defaults to Lastra; pass `{ format: 'parquet' }` for Parquet.
@@ -81,8 +144,95 @@ export class QTSurfer {
     return downloadKlines(args);
   }
 
+  /**
+   * List the exchanges the platform serves. Each `id` is what every other
+   * method takes as `exchangeId`.
+   *
+   * @throws QTSError on any non-2xx response, with the HTTP status on
+   * `status`.
+   */
+  exchanges(): Promise<Exchange[]> {
+    return listExchanges();
+  }
+
+  /**
+   * List an exchange's instruments, each with the per-data-type `coverage`
+   * that says which date windows are actually downloadable.
+   *
+   * Omitting `segment` asks for the exchange's **default** segment, which is
+   * `'spot'` today. The API answers with a HAL envelope that this method
+   * unwraps to the instrument array, so the envelope's `meta.segment`,
+   * `meta.updatedAt` and segment-discovery `_links` do not reach you: if you
+   * need certainty about which segment you are looking at, pass `segment`
+   * explicitly rather than relying on the default.
+   *
+   * @param exchangeId exchange identifier, e.g. `binance`
+   * @throws QTSError on any non-2xx response, with the HTTP status on
+   * `status`.
+   */
+  instruments(
+    exchangeId: string,
+    segment?: InstrumentSegment,
+  ): Promise<InstrumentDetail[]> {
+    return listInstruments(exchangeId, segment);
+  }
+
+  /**
+   * Ask the platform to check that a registered strategy can actually run:
+   * it instantiates the compiled class and drives it through a bounded
+   * synthetic series, so a wiring fault surfaces here instead of at the first
+   * backtest.
+   *
+   * **Idempotent, and two-outcome.** `queued: false` means a verdict already
+   * existed for the current compilation and came back unchanged in `state` —
+   * nothing was queued. `queued: true` means a check was just started, and is
+   * **not** terminal: poll {@link QTSurfer.strategy} until `validation`
+   * leaves `'pending'`. The discriminant reports whether work was *started*,
+   * not whether a verdict *exists*, because a `queued: false` answer can
+   * itself carry `validation: 'pending'` from a check an earlier call queued;
+   * `state.validation` is what tells you that.
+   *
+   * **Poll with a deadline of your own.** `'pending'` is not guaranteed to
+   * resolve — a queued check can go unreported for far longer than one takes,
+   * which the platform eventually flags as `validationStalled`. Nothing about
+   * the strategy is disproved when that happens, but a caller that waits for
+   * a terminal verdict without a timeout can wait forever. This SDK ships no
+   * polling helper for that reason: the timeout is the caller's policy.
+   *
+   * Whatever the verdict, it is a floor rather than a guarantee — see
+   * {@link StrategyState}.
+   *
+   * @param strategyId the id returned when the strategy was compiled
+   * @throws QTSError on any non-2xx response; a `404` (carried on `status`)
+   * means no such registered strategy for this caller.
+   */
+  validateStrategy(strategyId: string): Promise<StrategyValidation> {
+    return runValidateStrategy(strategyId);
+  }
+
+  /**
+   * Read everything the platform records about a strategy: whether it is
+   * registered at all, its validation verdict, the market data its compiled
+   * class requires, and any engine notices the check raised. This is what to
+   * poll after {@link QTSurfer.validateStrategy} returns `queued: true`, and
+   * the only place a verdict is read from.
+   *
+   * Check `compiledAt` against `validatedAt` before trusting a verdict: the
+   * strategy may have been recompiled since it was recorded, in which case
+   * the verdict describes bytecode that is no longer what would run.
+   * See {@link StrategyState} for why even a fresh `'passed'` is a floor
+   * rather than a guarantee.
+   *
+   * @param strategyId the id returned when the strategy was compiled
+   * @throws QTSError on any non-2xx response. A `404` (carried on `status`)
+   * means exactly one thing — no such registered strategy for this caller.
+   * It is never a stale or expired answer.
+   */
+  strategy(strategyId: string): Promise<StrategyState> {
+    return getStrategy(strategyId);
+  }
+
   // Future surface:
-  //   strategies: { compile, status, list }
-  //   instruments: { list, get } with TTL cache
+  //   TTL cache for exchanges / instruments
   //   jobs: { cancel, stream, result }
 }

package/src/errors.ts

@@ -2,8 +2,10 @@
  * Base class for every error the SDK throws. Catch this to handle all SDK
  * failures generically, or catch a specific subclass below to tell which
  * stage failed. `status` is only set when the throw site had an HTTP status
- * to attach — today that is just {@link QTSDownloadError}; the workflow-stage
- * errors carry `cause` instead and encode retryability in their message.
+ * to attach: {@link QTSDownloadError} always carries one, and so does the
+ * plain `QTSError` thrown by the single-request calls (`exchanges`,
+ * `instruments`, `validateStrategy`, `strategy`). The workflow-stage errors
+ * carry `cause` instead and encode retryability in their message.
  */
 export class QTSError extends Error {
   /** HTTP status code, when the underlying transport surfaced one. */

package/src/index.ts

@@ -22,7 +22,40 @@ export type {
   BacktestStage,
   BacktestOptions,
 } from './workflows/backtest';
+export type {
+  ParamAxis,
+  Sweep,
+  SweepAccepted,
+  SweepHeatmap,
+  SweepHeatmapCell,
+  SweepMarginal,
+  SweepMarginalPoint,
+  SweepObjective,
+  SweepOptions,
+  SweepOrder,
+  SweepProgress,
+  SweepProgressEvent,
+  SweepRanking,
+  SweepRequest,
+  SweepResult,
+  SweepRunRow,
+  SweepSampler,
+  SweepSensitivity,
+  SweepState,
+  SweepWalkForward,
+  WalkForwardFold,
+  WalkForwardResult,
+} from './workflows/sweep';
 export type { DownloadFormat } from './workflows/downloads';
+export type {
+  Exchange,
+  InstrumentDetail,
+  InstrumentSegment,
+} from './workflows/catalog';
+export type {
+  StrategyState,
+  StrategyValidation,
+} from './workflows/strategies';
 export {
   authenticate,
   AuthenticatedClient,

package/src/internal/polling.ts

@@ -0,0 +1,142 @@
+import {
+  ExponentialBackoff,
+  TaskCancelledError,
+  TimeoutStrategy,
+  handleWhenResult,
+  retry,
+  timeout,
+  wrap,
+  type ICancellationContext,
+  type IPolicy,
+} from 'cockatiel';
+import { QTSCanceledError, QTSTimeoutError } from '../errors';
+
+/**
+ * The stable form of a backend job/sweep status, so the rest of the SDK can
+ * reason about it regardless of OpenAPI spec drift (the live API sometimes
+ * returns lowercase values like `queued` / `completed` / `failed`).
+ *
+ * @internal
+ */
+export type NormalizedStatus = 'in-progress' | 'completed' | 'failed' | 'aborted';
+
+/**
+ * Normalize a raw status value.
+ *
+ * Only the terminal statuses end a poll loop. Everything else — including a
+ * **missing** status — means "keep asking": the API answers `202` with an empty body when a
+ * job is known but its result is not readable yet, and that response carries no state at all.
+ * Mapping absent to in-progress is what makes a 202 continue the loop under its timeout
+ * instead of being mistaken for a finished job with no data.
+ *
+ * @internal
+ */
+export function normalizeStatus(raw: unknown): NormalizedStatus {
+  const value = typeof raw === 'string' ? raw.toLowerCase() : '';
+  if (value === 'completed') return 'completed';
+  // A sweep that finishes with at least one shard dead reports `partial`, and that is
+  // terminal: the rows it did produce are readable and nothing more is coming, so treating it
+  // as in-progress would poll a finished sweep forever. `PARTIAL` exists only on the two sweep
+  // schemas (`ExecuteSweepResult.status` and `SweepSensitivity.status`) and is absent from
+  // `JobState`, so mapping it here cannot reach the prepare or execute paths. It folds into
+  // `completed` because this enum drives the poll loop — stop asking, hand the response back —
+  // and the caller reads `partial` off the response itself, where the distinction survives.
+  if (value === 'partial') return 'completed';
+  if (value === 'failed') return 'failed';
+  if (value === 'aborted' || value === 'cancelled' || value === 'canceled') {
+    return 'aborted';
+  }
+  // new / started / queued / running / absent (202) / anything else → still running
+  return 'in-progress';
+}
+
+/** The retry-with-backoff policy one workflow stage polls under. @internal */
+export type StagePolicy = IPolicy<ICancellationContext, never>;
+
+/** Poll tuning shared by every workflow's options object. @internal */
+export interface PollTuning {
+  pollIntervalMs?: number;
+  maxPollIntervalMs?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Build the poll policy for a workflow's stages.
+ *
+ * The defaults are a per-workflow argument rather than a constant, because how
+ * often it is worth asking depends on what is being watched: a single backtest
+ * advances tick by tick, while a sweep's leaderboard changes on the timescale
+ * of shards finishing.
+ *
+ * @param opts caller overrides
+ * @param defaultPollMs initial interval when the caller sets none
+ * @param defaultMaxPollMs backoff ceiling when the caller sets none
+ *
+ * @internal
+ */
+export function buildStagePolicy(
+  opts: PollTuning,
+  defaultPollMs: number,
+  defaultMaxPollMs: number,
+): StagePolicy {
+  const retryPolicy = retry(
+    handleWhenResult((r) => {
+      const status = (r as { status?: unknown } | undefined)?.status;
+      return normalizeStatus(status) === 'in-progress';
+    }),
+    {
+      maxAttempts: Number.MAX_SAFE_INTEGER,
+      backoff: new ExponentialBackoff({
+        initialDelay: opts.pollIntervalMs ?? defaultPollMs,
+        maxDelay: opts.maxPollIntervalMs ?? defaultMaxPollMs,
+      }),
+    },
+  );
+
+  return opts.timeoutMs
+    ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)
+    : retryPolicy;
+}
+
+/** How one call to {@link runStage} is cancelled and reported. @internal */
+export interface StageRun<T> {
+  /**
+   * Aborts the stage, surfacing as {@link QTSCanceledError}. Omit it to run a
+   * stage the caller's signal must **not** interrupt.
+   */
+  signal?: AbortSignal;
+  /** Only used to render the timeout message. */
+  timeoutMs?: number;
+  /** Called with every attempt's result, terminal or not. */
+  onEachAttempt?: (r: T) => void;
+}
+
+/**
+ * Poll `fetchFn` under `policy` until its result stops normalizing to
+ * `in-progress`, then return that result.
+ *
+ * @internal
+ */
+export async function runStage<T>(
+  policy: StagePolicy,
+  fetchFn: (ctx: ICancellationContext) => Promise<T>,
+  run: StageRun<T> = {},
+): Promise<T> {
+  try {
+    return await policy.execute(async (ctx) => {
+      if (run.signal?.aborted) throw new QTSCanceledError('Workflow aborted');
+      const result = await fetchFn(ctx);
+      run.onEachAttempt?.(result);
+      if (run.signal?.aborted) throw new QTSCanceledError('Workflow aborted');
+      return result;
+    }, run.signal);
+  } catch (err) {
+    if (err instanceof QTSCanceledError) throw err;
+    if (err instanceof TaskCancelledError) {
+      if (run.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);
+      throw new QTSTimeoutError(`Stage exceeded ${run.timeoutMs}ms`, err);
+    }
+    if (run.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);
+    throw err;
+  }
+}

package/src/internal/preparation.ts

@@ -0,0 +1,121 @@
+import {
+  getPrepareStatus,
+  compileStrategy as apiCompileStrategy,
+  prepareBacktest,
+  type DataSourceType,
+  type PrepareJobState,
+} from '@qtsurfer/api-client';
+import { QTSCanceledError, QTSPreparationError, QTSStrategyCompileError } from '../errors';
+import { normalizeStatus, runStage, type StagePolicy } from './polling';
+
+/** The only data source the workflows prepare against today. @internal */
+export const TICKER: DataSourceType = 'ticker';
+
+/**
+ * Compile in a single request: the API answers synchronously with the `strategyId`,
+ * so there is no job to poll. A compile error arrives here as a `400`, not on a later poll.
+ *
+ * @internal
+ */
+export async function compileStrategySource(
+  source: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const { data, error, response } = await apiCompileStrategy({
+    body: source,
+    ...(signal ? { signal } : {}),
+  });
+
+  if (error) {
+    // A 429 means the platform is holding too many compilations at once and the source was never
+    // judged — worth separating from the 400 that says the source itself does not compile.
+    // Read the status inside this branch and optionally: a transport failure carries no response,
+    // and dereferencing one would raise a TypeError that buries the error actually being reported.
+    if (response?.status === 429) {
+      throw new QTSStrategyCompileError(
+        'Strategy was not compiled, too many compilations in flight; retry later',
+        error,
+      );
+    }
+    throw new QTSStrategyCompileError('Strategy compilation failed', error);
+  }
+  if (!data?.strategyId) {
+    throw new QTSStrategyCompileError('Compile response missing strategyId');
+  }
+  return data.strategyId;
+}
+
+/** The instrument and window one prepare covers. @internal */
+export interface PrepareTarget {
+  exchangeId: string;
+  instrument: string;
+  from: string;
+  to: string;
+}
+
+/** Reporting and cancellation for {@link prepareDataset}. @internal */
+export interface PrepareRun {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Called after each poll that reports size information. */
+  onPercent?: (percent: number) => void;
+  /** Called once with the terminal state, so the caller can read its coverage. */
+  onPrepared?: (state: PrepareJobState) => void;
+}
+
+/**
+ * Submit a prepare and poll it to a terminal state.
+ *
+ * One implementation on purpose. Preparing is idempotent — the same instrument
+ * and window always resolve to the same job — so a workflow that prepares on
+ * every call duplicates no work, and that argument only holds while there is a
+ * single place where it is true.
+ *
+ * @returns the prepare jobId, which is what identifies the prepared dataset
+ *
+ * @internal
+ */
+export async function prepareDataset(
+  target: PrepareTarget,
+  policy: StagePolicy,
+  run: PrepareRun = {},
+): Promise<string> {
+  const { data, error } = await prepareBacktest({
+    path: { exchangeId: target.exchangeId, type: TICKER },
+    body: { instrument: target.instrument, from: target.from, to: target.to },
+    ...(run.signal ? { signal: run.signal } : {}),
+  });
+  if (error) throw new QTSPreparationError('Prepare submission failed', error);
+  if (!data?.jobId) throw new QTSPreparationError('Missing jobId in prepare response');
+
+  const prepareJobId = data.jobId;
+  const state = await runStage(
+    policy,
+    async ({ signal }) => {
+      const res = await getPrepareStatus({
+        path: { exchangeId: target.exchangeId, type: TICKER, jobId: prepareJobId },
+        signal,
+      });
+      if (res.error) throw new QTSPreparationError('Preparation status request failed', res.error);
+      if (!res.data) throw new QTSPreparationError('Empty preparation status response');
+      return res.data;
+    },
+    {
+      ...(run.signal ? { signal: run.signal } : {}),
+      ...(run.timeoutMs !== undefined ? { timeoutMs: run.timeoutMs } : {}),
+      onEachAttempt: (r) => {
+        if (r.size > 0) run.onPercent?.((r.completed / r.size) * 100);
+      },
+    },
+  );
+
+  const prepNorm = normalizeStatus(state.status);
+  if (prepNorm === 'failed') {
+    throw new QTSPreparationError(state.statusDetail ?? 'Data preparation failed');
+  }
+  if (prepNorm === 'aborted') {
+    throw new QTSCanceledError('Data preparation aborted');
+  }
+  run.onPrepared?.(state);
+  return prepareJobId;
+}

package/src/internal/requestError.ts

@@ -0,0 +1,36 @@
+import { QTSError } from '../errors';
+
+/**
+ * Build the {@link QTSError} for a failed single-request call.
+ *
+ * The HTTP status is attached to the error rather than only rendered into the
+ * message, because callers branch on it — a `4xx` means the request itself was
+ * wrong, a `5xx` is generally worth retrying, and the authenticated session
+ * re-mints its JWT on a `401`.
+ *
+ * @param what short description of the call, e.g. `'exchanges call'`
+ * @param error the api-client error payload
+ * @param status HTTP status of the failing response
+ *
+ * @internal
+ */
+export function requestFailed(
+  what: string,
+  error: unknown,
+  status?: number,
+): QTSError {
+  const prefix = status === undefined ? '' : `HTTP ${status} — `;
+  return new QTSError(`${what} failed: ${prefix}${describe(error)}`, error, status);
+}
+
+function describe(error: unknown): string {
+  if (error && typeof error === 'object') {
+    const e = error as { code?: unknown; message?: unknown };
+    const code = typeof e.code === 'string' || typeof e.code === 'number' ? e.code : undefined;
+    const message = typeof e.message === 'string' ? e.message : undefined;
+    if (code !== undefined && message) return `${code}: ${message}`;
+    if (message) return message;
+    if (code !== undefined) return String(code);
+  }
+  return String(error);
+}