@qtsurfer/sdk 0.7.0 → 0.8.0

package/src/workflows/backtest.ts

@@ -2,30 +2,20 @@ import {
   cancelBacktest,
   executeBacktest,
   getBacktestResult,
-  getPrepareStatus,
-  compileStrategy as apiCompileStrategy,
-  prepareBacktest,
-  type DataSourceType,
   type ResultMap,
 } from '@qtsurfer/api-client';
+import { QTSCanceledError, QTSExecutionError } from '../errors';
 import {
-  ExponentialBackoff,
-  TaskCancelledError,
-  TimeoutStrategy,
-  handleWhenResult,
-  retry,
-  timeout,
-  wrap,
-  type IPolicy,
-  type ICancellationContext,
-} from 'cockatiel';
+  buildStagePolicy,
+  normalizeStatus,
+  runStage,
+  type StagePolicy,
+} from '../internal/polling';
 import {
-  QTSCanceledError,
-  QTSExecutionError,
-  QTSPreparationError,
-  QTSStrategyCompileError,
-  QTSTimeoutError,
-} from '../errors';
+  TICKER,
+  compileStrategySource,
+  prepareDataset,
+} from '../internal/preparation';
 
 export interface BacktestRequest {
   /** Strategy source code (Java) */
@@ -79,43 +69,20 @@ export interface BacktestOptions {
   timeoutMs?: number;
 }
 
-const TICKER: DataSourceType = 'ticker';
-
-type JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
-
-/**
- * Normalize the backend job status to a stable lowercase form so we can
- * reason about it regardless of OpenAPI spec drift (the live API sometimes
- * returns lowercase values like `queued` / `completed` / `failed`).
- *
- * Only the three 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.
- */
-type NormalizedStatus = 'in-progress' | 'completed' | 'failed' | 'aborted';
-
-function normalizeStatus(raw: unknown): NormalizedStatus {
-  const value = typeof raw === 'string' ? raw.toLowerCase() : '';
-  if (value === 'completed') 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';
-}
+/** Initial interval between polls of a single backtest. */
+const DEFAULT_POLL_INTERVAL_MS = 500;
+/** Backoff ceiling for a single backtest. */
+const DEFAULT_MAX_POLL_INTERVAL_MS = 5000;
 
 export async function backtest(
   req: BacktestRequest,
   opts: BacktestOptions = {},
 ): Promise<BacktestResult> {
-  const policy = buildStagePolicy(opts);
+  const policy = buildStagePolicy(opts, DEFAULT_POLL_INTERVAL_MS, DEFAULT_MAX_POLL_INTERVAL_MS);
 
   // 1. Compile strategy (single synchronous request)
   opts.onProgress?.({ stage: 'compiling' });
-  const strategyId = await compileStrategy(req.strategy, opts);
+  const strategyId = await compileStrategySource(req.strategy, opts.signal);
 
   // 2. Prepare data
   opts.onProgress?.({ stage: 'preparing' });
@@ -126,106 +93,40 @@ export async function backtest(
   return executeStrategy(req, prepareJobId, strategyId, policy, opts);
 }
 
-function buildStagePolicy(opts: BacktestOptions): IPolicy<ICancellationContext, never> {
-  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 ?? 500,
-        maxDelay: opts.maxPollIntervalMs ?? 5000,
-      }),
-    },
-  );
-
-  return opts.timeoutMs
-    ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)
-    : retryPolicy;
-}
-
-/**
- * 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.
- */
-async function compileStrategy(source: string, opts: BacktestOptions): Promise<string> {
-  const { data, error, response } = await apiCompileStrategy({
-    body: source,
-    ...(opts.signal ? { signal: opts.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;
-}
-
-async function prepareData(
+function prepareData(
   req: BacktestRequest,
-  policy: IPolicy<ICancellationContext, never>,
+  policy: StagePolicy,
   opts: BacktestOptions,
 ): Promise<string> {
-  const { data, error } = await prepareBacktest({
-    path: { exchangeId: req.exchangeId, type: TICKER },
-    body: { instrument: req.instrument, from: req.from, to: req.to },
-    ...(opts.signal ? { signal: opts.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,
-    opts,
-    async ({ signal }) => {
-      const res = await getPrepareStatus({
-        path: { exchangeId: req.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;
+  return prepareDataset(
+    {
+      exchangeId: req.exchangeId,
+      instrument: req.instrument,
+      from: req.from,
+      to: req.to,
     },
-    (r) => {
-      if (r.size > 0) {
-        opts.onProgress?.({ stage: 'preparing', percent: (r.completed / r.size) * 100 });
-      }
+    policy,
+    {
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+      onPercent: (percent) => opts.onProgress?.({ stage: 'preparing', percent }),
+      // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the
+      // final preparing event, so callers can react to a partially-covered range.
+      onPrepared: (state) =>
+        opts.onProgress?.({
+          stage: 'preparing',
+          percent: 100,
+          coverageRatio: state.coverageRatio,
+        }),
     },
   );
-
-  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');
-  }
-  // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the
-  // final preparing event, so callers can react to a partially-covered range.
-  opts.onProgress?.({ stage: 'preparing', percent: 100, coverageRatio: state.coverageRatio });
-  return prepareJobId;
 }
 
 async function executeStrategy(
   req: BacktestRequest,
   prepareJobId: string,
   strategyId: string,
-  policy: IPolicy<ICancellationContext, never>,
+  policy: StagePolicy,
   opts: BacktestOptions,
 ): Promise<BacktestResult> {
   const { data, error } = await executeBacktest({
@@ -245,7 +146,6 @@ async function executeStrategy(
   try {
     const finalResult = await runStage(
       policy,
-      opts,
       async ({ signal }) => {
         const res = await getBacktestResult({
           path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
@@ -258,10 +158,14 @@ async function executeStrategy(
         // see normalizeStatus. Do not "fix" this into a throw or an early return of the result.
         return { ...res.data.state, __result: res.data.results };
       },
-      (r) => {
-        if (r.size > 0) {
-          opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });
-        }
+      {
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        onEachAttempt: (r) => {
+          if (r.size > 0) {
+            opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });
+          }
+        },
       },
     );
 
@@ -282,28 +186,3 @@ async function executeStrategy(
     throw err;
   }
 }
-
-async function runStage<T extends { status: JobStatus }>(
-  policy: IPolicy<ICancellationContext, never>,
-  opts: BacktestOptions,
-  fetchFn: (ctx: ICancellationContext) => Promise<T>,
-  onEachAttempt?: (r: T) => void,
-): Promise<T> {
-  try {
-    return await policy.execute(async (ctx) => {
-      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');
-      const result = await fetchFn(ctx);
-      onEachAttempt?.(result);
-      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');
-      return result;
-    }, opts.signal);
-  } catch (err) {
-    if (err instanceof QTSCanceledError) throw err;
-    if (err instanceof TaskCancelledError) {
-      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);
-      throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);
-    }
-    if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);
-    throw err;
-  }
-}

package/src/workflows/catalog.ts

@@ -0,0 +1,74 @@
+import {
+  listExchanges as apiListExchanges,
+  listInstruments as apiListInstruments,
+  listSegmentInstruments as apiListSegmentInstruments,
+  type Exchange as ApiExchange,
+  type InstrumentDetail as ApiInstrumentDetail,
+} from '@qtsurfer/api-client';
+import { QTSError } from '../errors';
+import { requestFailed } from '../internal/requestError';
+
+/**
+ * One exchange the platform serves. Alias for api-client's `Exchange`:
+ * `id` (what every other call takes as `exchangeId`), `name`, and an
+ * optional `description`.
+ */
+export type Exchange = ApiExchange;
+
+/**
+ * One instrument on an exchange. Alias for api-client's `InstrumentDetail`:
+ * `id` / `base` / `quote`, plus optional `coverage` (the date windows for
+ * which tickers and klines actually exist, per data type), `lastPrice` and
+ * `volume24h`.
+ *
+ * `coverage` is what tells you whether a backtest range is downloadable at
+ * all; it is optional, and absent means the platform did not report one, not
+ * that there is no data.
+ */
+export type InstrumentDetail = ApiInstrumentDetail;
+
+/**
+ * A market segment of an exchange. `'spot'` is the default segment served
+ * when {@link QTSurfer.instruments} is called without one.
+ */
+export type InstrumentSegment = 'spot' | 'futures';
+
+/**
+ * List the exchanges the platform serves.
+ *
+ * @throws QTSError on any non-2xx response, with the HTTP status on `status`.
+ */
+export async function listExchanges(): Promise<Exchange[]> {
+  const { data, error, response } = await apiListExchanges();
+  if (error) throw requestFailed('exchanges call', error, response?.status);
+  if (!data) throw new QTSError('Empty exchanges response');
+  return data;
+}
+
+/**
+ * List an exchange's instruments, each with its per-data-type coverage.
+ *
+ * Omitting `segment` asks for the exchange's **default** segment, which is
+ * `'spot'` today. The API answers both routes with a HAL envelope
+ * (`data` / `meta` / `_links`) that this function unwraps to the instrument
+ * array, so `meta.segment`, `meta.updatedAt` and the `_links`
+ * segment-discovery links do not reach the caller: 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`
+ * @param segment market segment to list; defaults to the exchange's default
+ * segment
+ * @throws QTSError on any non-2xx response, with the HTTP status on `status`.
+ */
+export async function listInstruments(
+  exchangeId: string,
+  segment?: InstrumentSegment,
+): Promise<InstrumentDetail[]> {
+  const { data, error, response } = segment
+    ? await apiListSegmentInstruments({ path: { exchangeId, segment } })
+    : await apiListInstruments({ path: { exchangeId } });
+  if (error) throw requestFailed('instruments call', error, response?.status);
+  if (!data) throw new QTSError('Empty instruments response');
+  return data.data;
+}

package/src/workflows/strategies.ts

@@ -0,0 +1,118 @@
+import {
+  getStrategy as apiGetStrategy,
+  validateStrategy as apiValidateStrategy,
+  type StrategyState as ApiStrategyState,
+} from '@qtsurfer/api-client';
+import { QTSError } from '../errors';
+import { requestFailed } from '../internal/requestError';
+
+/**
+ * Everything the platform records about a registered strategy. Alias for
+ * api-client's `StrategyState`.
+ *
+ * `validation` is the verdict and is one of:
+ *
+ * - `'not_validated'` — registered, never checked.
+ * - `'pending'` — a check was asked for and has not answered yet.
+ * - `'passed'` — the class loaded and survived its first event.
+ * - `'failed'` — it did not; `detail` says how.
+ *
+ * **`'passed'` is a floor, not a guarantee.** It means the compiled class
+ * could be instantiated and got through the first event of a short synthetic
+ * run — not the caller's instrument, not the caller's window, and not the
+ * rest of the run. It says nothing about whether the strategy is correct,
+ * profitable, or safe to run at scale. `dryRunIncomplete` marks a check that
+ * ran out of its budget, which makes a `'passed'` verdict a lower floor
+ * still, and makes an empty `notices` list no longer a clean bill of health.
+ *
+ * A verdict describes the bytecode that existed when it was recorded:
+ * `compiledAt` newer than `validatedAt` means the strategy was recompiled
+ * afterwards and the verdict no longer describes what would run.
+ */
+export type StrategyState = ApiStrategyState;
+
+/**
+ * Outcome of {@link QTSurfer.validateStrategy} — the SDK's rendering of the
+ * two answers that operation has, which the response body alone cannot tell
+ * apart.
+ *
+ * - `queued: false` — a verdict already existed for the current compilation
+ *   and comes back in `state` unchanged; nothing new was queued. This is
+ *   **not** the same as "terminal": a check queued by an earlier call can
+ *   still be running, so read `state.validation` rather than treating
+ *   `queued: false` as "there is an answer".
+ * - `queued: true` — a check was just queued. Nothing is known yet; poll
+ *   {@link QTSurfer.strategy} until `validation` leaves `'pending'`.
+ */
+export type StrategyValidation =
+  | { queued: false; strategyId: string; state: StrategyState }
+  | { queued: true; strategyId: string; state?: undefined };
+
+/**
+ * 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.** If a verdict already exists for the
+ * current compilation it is returned unchanged and nothing is queued
+ * (`queued: false`); otherwise a check is queued (`queued: true`) and this
+ * call is *not* terminal — poll {@link QTSurfer.strategy} until `validation`
+ * is `'passed'` or `'failed'`. Because a `queued: false` answer can itself carry
+ * `validation: 'pending'` (a check an earlier call queued), the discriminant
+ * tells you whether work was *started*, not whether a verdict *exists*;
+ * `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` on the strategy.
+ * Nothing about the strategy is disproved when that happens — the check
+ * simply did not run — but a caller that waits for a terminal verdict without
+ * a timeout can wait forever. This SDK deliberately ships no polling helper
+ * for that reason; the timeout is the caller's policy to set.
+ *
+ * Whatever the verdict, remember 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.
+ */
+export async function validateStrategy(strategyId: string): Promise<StrategyValidation> {
+  const { data, error, response } = await apiValidateStrategy({ path: { strategyId } });
+  if (error) throw requestFailed('strategy validation request', error, response?.status);
+  // The two outcomes are distinguishable only by status: a `200` body is a
+  // full StrategyState whose `validation` may itself be `'pending'`, so the
+  // payload cannot be used to tell "queued just now" from "already queued".
+  // The queued branch echoes back the caller's own id rather than reading one
+  // out of the body, because an accepted-but-not-done response on this API is
+  // not guaranteed to carry a body at all.
+  if (response?.status === 202) return { queued: true, strategyId };
+  if (!data) throw new QTSError('Empty strategy validation response');
+  return { queued: false, strategyId, state: data as StrategyState };
+}
+
+/**
+ * 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 the endpoint 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 the verdict was recorded, in which
+ * case the verdict describes bytecode that is no longer what would run.
+ * Re-request validation to get an answer about the current compilation.
+ *
+ * @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: registration and verdict are stored
+ * durably, not cached.
+ */
+export async function getStrategy(strategyId: string): Promise<StrategyState> {
+  const { data, error, response } = await apiGetStrategy({ path: { strategyId } });
+  if (error) throw requestFailed('strategy lookup', error, response?.status);
+  if (!data) throw new QTSError('Empty strategy response');
+  return data;
+}