@qtsurfer/sdk 0.8.0 → 0.10.0

package/src/auth/session.ts

@@ -24,8 +24,12 @@ import {
 import {
   getStrategy,
   validateStrategy as runValidateStrategy,
+  listStrategies,
+  deleteStrategy as runDeleteStrategy,
+  getStrategyCode,
   type StrategyState,
   type StrategyValidation,
+  type StrategySummary,
 } from '../workflows/strategies';
 import {
   sweep as runSweep,
@@ -238,6 +242,33 @@ export class AuthenticatedClient {
   strategy(strategyId: string): Promise<StrategyState> {
     return this.withRefreshOn401(() => getStrategy(strategyId));
   }
+
+  /**
+   * List every strategy you have registered and not deleted, most recently
+   * compiled first. Refreshes the token once on `401` before retrying. See
+   * {@link QTSurfer.strategies}.
+   */
+  strategies(): Promise<StrategySummary[]> {
+    return this.withRefreshOn401(() => listStrategies());
+  }
+
+  /**
+   * Release a registered strategy. Refreshes the token once on `401` before
+   * retrying. See {@link QTSurfer.deleteStrategy} for what this does and
+   * does not undo.
+   */
+  deleteStrategy(strategyId: string): Promise<void> {
+    return this.withRefreshOn401(() => runDeleteStrategy(strategyId));
+  }
+
+  /**
+   * Read back a strategy's exact registered source. Refreshes the token
+   * once on `401` before retrying. See {@link QTSurfer.strategyCode} for
+   * what its `404` covers.
+   */
+  strategyCode(strategyId: string): Promise<string> {
+    return this.withRefreshOn401(() => getStrategyCode(strategyId));
+  }
 }
 
 /**
@@ -247,7 +278,8 @@ export class AuthenticatedClient {
  * environment. The returned {@link AuthenticatedClient} caches the JWT,
  * refreshes it on 401, and exposes the same surface as `QTSurfer`
  * (`backtest`, `sweep`, `tickers`, `klines`, `exchanges`, `instruments`,
- * `validateStrategy`, `strategy`).
+ * `validateStrategy`, `strategy`, `strategies`, `deleteStrategy`,
+ * `strategyCode`).
  *
  * @throws {QTSAuthError} if no apikey is supplied or available in env.
  */

package/src/client.ts

@@ -20,8 +20,12 @@ import {
 import {
   getStrategy,
   validateStrategy as runValidateStrategy,
+  listStrategies,
+  deleteStrategy as runDeleteStrategy,
+  getStrategyCode,
   type StrategyState,
   type StrategyValidation,
+  type StrategySummary,
 } from './workflows/strategies';
 import {
   sweep as runSweep,
@@ -62,7 +66,7 @@ export interface DownloadHourArgs {
  * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's
  * workflow methods (`backtest`, `sweep`, `tickers`, `klines`), the platform catalog
  * (`exchanges`, `instruments`) and the strategy surface (`validateStrategy`,
- * `strategy`). Constructing an
+ * `strategy`, `strategies`, `deleteStrategy`, `strategyCode`). 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
@@ -107,7 +111,8 @@ export class QTSurfer {
    * 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.
+   * walk-forward block with fewer than two folds, or naming both/neither of
+   * `instrument`/`datasetId`) 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
@@ -232,6 +237,51 @@ export class QTSurfer {
     return getStrategy(strategyId);
   }
 
+  /**
+   * List every strategy you have registered and not deleted, most recently
+   * compiled first. Never `404`s — an empty array means you have none.
+   * Each entry deliberately omits `validation`; check a specific strategy's
+   * verdict with {@link QTSurfer.strategy}. See {@link StrategySummary}.
+   *
+   * @throws QTSError on any non-2xx response, with the HTTP status on
+   * `status`.
+   */
+  strategies(): Promise<StrategySummary[]> {
+    return listStrategies();
+  }
+
+  /**
+   * Release a registered strategy: removes it from both {@link
+   * QTSurfer.strategy} and {@link QTSurfer.strategies}.
+   *
+   * Backtests already run against this strategy are unaffected, and
+   * re-submitting the same source afterwards registers a **new** strategy
+   * with a **new** id rather than undeleting this one. Deleting your own
+   * copy of a strategy never affects anyone else's copy of the same source
+   * (e.g. a shared/marketplace listing).
+   *
+   * @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.
+   */
+  deleteStrategy(strategyId: string): Promise<void> {
+    return runDeleteStrategy(strategyId);
+  }
+
+  /**
+   * Read back the exact source last submitted for a strategy id, whitespace
+   * and comments included.
+   *
+   * A `404` (carried on `status`) covers two indistinguishable cases: the id
+   * was never registered by you, or it resolves only through a shared/
+   * marketplace reference that carries no source of its own.
+   *
+   * @param strategyId the id returned when the strategy was compiled
+   */
+  strategyCode(strategyId: string): Promise<string> {
+    return getStrategyCode(strategyId);
+  }
+
   // Future surface:
   //   TTL cache for exchanges / instruments
   //   jobs: { cancel, stream, result }

package/src/index.ts

@@ -55,6 +55,7 @@ export type {
 export type {
   StrategyState,
   StrategyValidation,
+  StrategySummary,
 } from './workflows/strategies';
 export {
   authenticate,

package/src/internal/preparation.ts

@@ -5,7 +5,7 @@ import {
   type DataSourceType,
   type PrepareJobState,
 } from '@qtsurfer/api-client';
-import { QTSCanceledError, QTSPreparationError, QTSStrategyCompileError } from '../errors';
+import { QTSCanceledError, QTSError, QTSPreparationError, QTSStrategyCompileError } from '../errors';
 import { normalizeStatus, runStage, type StagePolicy } from './polling';
 
 /** The only data source the workflows prepare against today. @internal */
@@ -45,14 +45,52 @@ export async function compileStrategySource(
   return data.strategyId;
 }
 
-/** The instrument and window one prepare covers. @internal */
+/**
+ * The instrument (or dataset) and window one prepare covers. Exactly one of
+ * `instrument`/`datasetId` is set — {@link validatePrepareTarget} enforces that
+ * before any network call. `datasetId` pairs with the reserved `exchangeId: 'user'`.
+ *
+ * @internal
+ */
 export interface PrepareTarget {
   exchangeId: string;
-  instrument: string;
+  instrument?: string;
+  /** Id of a previously uploaded dataset, in place of `instrument`. */
+  datasetId?: string;
+  /** Optional specific version of `datasetId`; requires `datasetId`. */
+  datasetVersionId?: string;
   from: string;
   to: string;
 }
 
+/**
+ * Reject a prepare target that names both, or neither, of `instrument`/`datasetId`,
+ * or that sets `datasetVersionId` without `datasetId` — the same three shapes the
+ * platform would only reject over the network. Called first thing by each workflow,
+ * before compiling the strategy, so a malformed request never reaches the network.
+ *
+ * @param workflow name of the caller, used to prefix the error message (e.g. `'backtest'`)
+ * @internal
+ */
+export function validatePrepareTarget(
+  workflow: string,
+  target: Pick<PrepareTarget, 'instrument' | 'datasetId' | 'datasetVersionId'>,
+): void {
+  const hasInstrument = target.instrument !== undefined;
+  const hasDataset = target.datasetId !== undefined;
+  if (hasInstrument && hasDataset) {
+    throw new QTSError(`${workflow}: exactly one of instrument/datasetId is required, got both`);
+  }
+  if (!hasInstrument && !hasDataset) {
+    throw new QTSError(
+      `${workflow}: exactly one of instrument/datasetId is required, got neither`,
+    );
+  }
+  if (target.datasetVersionId !== undefined && !hasDataset) {
+    throw new QTSError(`${workflow}: datasetVersionId requires datasetId`);
+  }
+}
+
 /** Reporting and cancellation for {@link prepareDataset}. @internal */
 export interface PrepareRun {
   signal?: AbortSignal;
@@ -82,7 +120,15 @@ export async function prepareDataset(
 ): Promise<string> {
   const { data, error } = await prepareBacktest({
     path: { exchangeId: target.exchangeId, type: TICKER },
-    body: { instrument: target.instrument, from: target.from, to: target.to },
+    body: {
+      ...(target.instrument !== undefined ? { instrument: target.instrument } : {}),
+      ...(target.datasetId !== undefined ? { datasetId: target.datasetId } : {}),
+      ...(target.datasetVersionId !== undefined
+        ? { datasetVersionId: target.datasetVersionId }
+        : {}),
+      from: target.from,
+      to: target.to,
+    },
     ...(run.signal ? { signal: run.signal } : {}),
   });
   if (error) throw new QTSPreparationError('Prepare submission failed', error);

package/src/workflows/backtest.ts

@@ -15,15 +15,47 @@ import {
   TICKER,
   compileStrategySource,
   prepareDataset,
+  validatePrepareTarget,
 } from '../internal/preparation';
 
+/**
+ * ```ts
+ * const request: BacktestRequest = {
+ *   strategy: source,
+ *   exchangeId: 'binance',
+ *   instrument: 'BTC/USDT',
+ *   from: '2026-01-01T00:00:00Z',
+ *   to: '2026-02-01T00:00:00Z',
+ * };
+ * ```
+ *
+ * Backtest against a dataset you uploaded instead of an exchange instrument by
+ * replacing `instrument` with `datasetId` (and `exchangeId: 'user'`):
+ *
+ * ```ts
+ * const request: BacktestRequest = {
+ *   strategy: source,
+ *   exchangeId: 'user',
+ *   datasetId: 'ds_123',
+ *   from: '2026-01-01T00:00:00Z',
+ *   to: '2026-02-01T00:00:00Z',
+ * };
+ * ```
+ */
 export interface BacktestRequest {
   /** Strategy source code (Java) */
   strategy: string;
-  /** Exchange id, e.g. `binance` */
+  /** Exchange id, e.g. `binance`, or the reserved value `user` when backtesting against `datasetId`. */
   exchangeId: string;
-  /** Instrument symbol, e.g. `BTC/USDT` */
-  instrument: string;
+  /** Instrument symbol, e.g. `BTC/USDT`. Exactly one of `instrument`/`datasetId` is required. */
+  instrument?: string;
+  /**
+   * Id of a dataset you uploaded, in place of `instrument`. Exactly one of
+   * `instrument`/`datasetId` is required. Pairs with `exchangeId: 'user'`.
+   */
+  datasetId?: string;
+  /** Optional specific version of `datasetId`; omit to use its current version. Requires `datasetId`. */
+  datasetVersionId?: string;
   /** Date range start (ISO-8601, ISO DATE or BASIC ISO DATE) */
   from: string;
   /** Date range end (same formats as `from`) */
@@ -78,6 +110,7 @@ export async function backtest(
   req: BacktestRequest,
   opts: BacktestOptions = {},
 ): Promise<BacktestResult> {
+  validatePrepareTarget('backtest', req);
   const policy = buildStagePolicy(opts, DEFAULT_POLL_INTERVAL_MS, DEFAULT_MAX_POLL_INTERVAL_MS);
 
   // 1. Compile strategy (single synchronous request)
@@ -101,7 +134,9 @@ function prepareData(
   return prepareDataset(
     {
       exchangeId: req.exchangeId,
-      instrument: req.instrument,
+      ...(req.instrument !== undefined ? { instrument: req.instrument } : {}),
+      ...(req.datasetId !== undefined ? { datasetId: req.datasetId } : {}),
+      ...(req.datasetVersionId !== undefined ? { datasetVersionId: req.datasetVersionId } : {}),
       from: req.from,
       to: req.to,
     },

package/src/workflows/strategies.ts

@@ -1,7 +1,11 @@
 import {
   getStrategy as apiGetStrategy,
   validateStrategy as apiValidateStrategy,
+  listStrategies as apiListStrategies,
+  deleteStrategy as apiDeleteStrategy,
+  getStrategyCode as apiGetStrategyCode,
   type StrategyState as ApiStrategyState,
+  type StrategySummary as ApiStrategySummary,
 } from '@qtsurfer/api-client';
 import { QTSError } from '../errors';
 import { requestFailed } from '../internal/requestError';
@@ -28,6 +32,15 @@ import { requestFailed } from '../internal/requestError';
  * 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.
+ *
+ * `_links.code`, when present, is a discovery link to this strategy's raw
+ * source (`GET /strategy/{strategyId}/code` — the same thing
+ * {@link QTSurfer.strategyCode} fetches by id, so there is no need to follow
+ * the link yourself). It is present on a full `StrategyState` body — this
+ * function's result, and {@link QTSurfer.validateStrategy}'s already-validated
+ * `200` — and **absent** from that same operation's `queued: true` (`202`)
+ * outcome, which is a deliberately partial stub. This field passes through
+ * unmodified from api-client, so it needs no unwrapping on the SDK's part.
  */
 export type StrategyState = ApiStrategyState;
 
@@ -116,3 +129,88 @@ export async function getStrategy(strategyId: string): Promise<StrategyState> {
   if (!data) throw new QTSError('Empty strategy response');
   return data;
 }
+
+/**
+ * One entry in {@link QTSurfer.strategies}'s result: the same provenance
+ * {@link QTSurfer.strategy} reports — `compiledAt`, `requiredSources` — but
+ * never `validation`, which is what keeps listing cheap no matter how many
+ * strategies you have registered. Check a specific strategy's verdict with
+ * {@link QTSurfer.strategy}.
+ *
+ * Note: the spec types this endpoint's `requiredSources` as a plain
+ * `string[]`, not the `'Ticker' | 'KLine' | 'FundingRate'` union that
+ * {@link StrategyState}'s own `requiredSources` carries — narrow it yourself
+ * if you need the literal type. Alias for api-client's `StrategySummary`.
+ */
+export type StrategySummary = ApiStrategySummary;
+
+/**
+ * List every strategy you have registered and not deleted, most recently
+ * compiled first.
+ *
+ * **Never `404`.** An empty array means you have none registered — not an
+ * error. Each entry omits `validation` on purpose (see {@link
+ * StrategySummary}); check a specific strategy's verdict with {@link
+ * QTSurfer.strategy}.
+ *
+ * @throws QTSError on any non-2xx response, with the HTTP status on `status`.
+ */
+export async function listStrategies(): Promise<StrategySummary[]> {
+  const { data, error, response } = await apiListStrategies();
+  if (error) throw requestFailed('strategies list', error, response?.status);
+  if (!data) throw new QTSError('Empty strategies response');
+  return data.strategies;
+}
+
+/**
+ * Release a registered strategy: removes it from both {@link
+ * QTSurfer.strategy} and {@link QTSurfer.strategies}.
+ *
+ * **Does not undo anything already run.** Backtests you ran against this
+ * strategy before deleting it are completely unaffected — deleting only
+ * stops you from validating or re-running it under this id going forward.
+ * Re-submitting the exact same source afterwards registers a **new**
+ * strategy with a **new** id; it does not "undelete" this one, because
+ * nothing about the id itself is restored.
+ *
+ * **Scoped to your own registration.** If you copied someone else's strategy
+ * (a shared/marketplace listing), deleting your copy never affects theirs,
+ * or anyone else's, regardless of how many callers registered the same
+ * source independently.
+ *
+ * Resolves with nothing: the response body is `{ strategyId, deleted: true }`,
+ * and both fields are things the caller already knows before calling this —
+ * `strategyId` is the argument just passed in, and `deleted` is always `true`
+ * on a `200`. There is nothing in it a `void` return would lose.
+ *
+ * @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 deleteStrategy(strategyId: string): Promise<void> {
+  const { error, response } = await apiDeleteStrategy({ path: { strategyId } });
+  if (error) throw requestFailed('strategy delete', error, response?.status);
+}
+
+/**
+ * Read back the exact source last submitted for a strategy id — the same
+ * text `strategyId` was derived from, whitespace and comments included.
+ *
+ * **A `404` here covers two cases the response cannot tell apart:** the id
+ * was never registered by you, or it resolves only through a shared/
+ * marketplace reference that carries no source of its own (a strategy you
+ * copied by reference rather than by resubmitting its code). Both read as
+ * "nothing to return" from this endpoint's point of view, and the SDK does
+ * not attempt to distinguish them — there is nothing in the response to tell
+ * them apart with.
+ *
+ * @param strategyId the id returned when the strategy was compiled
+ * @throws QTSError on any non-2xx response; a `404` (carried on `status`)
+ * is the two-case ambiguity described above.
+ */
+export async function getStrategyCode(strategyId: string): Promise<string> {
+  const { data, error, response } = await apiGetStrategyCode({ path: { strategyId } });
+  if (error) throw requestFailed('strategy code lookup', error, response?.status);
+  if (!data) throw new QTSError('Empty strategy code response');
+  return data.code;
+}

package/src/workflows/sweep.ts

@@ -25,7 +25,12 @@ import {
   runStage,
   type StagePolicy,
 } from '../internal/polling';
-import { TICKER, compileStrategySource, prepareDataset } from '../internal/preparation';
+import {
+  TICKER,
+  compileStrategySource,
+  prepareDataset,
+  validatePrepareTarget,
+} from '../internal/preparation';
 import { requestFailed } from '../internal/requestError';
 import type { BacktestStage } from './backtest';
 
@@ -291,14 +296,35 @@ export type WalkForwardFold = ApiWalkForwardFold;
  *   objective: 'sharpe',
  * };
  * ```
+ *
+ * Sweep against a dataset you uploaded instead of an exchange instrument by
+ * replacing `instrument` with `datasetId` (and `exchangeId: 'user'`):
+ *
+ * ```ts
+ * const request: SweepRequest = {
+ *   strategy: source,
+ *   exchangeId: 'user',
+ *   datasetId: 'ds_123',
+ *   from: '2026-01-01T00:00:00Z',
+ *   to: '2026-02-01T00:00:00Z',
+ *   params: { rsiPeriod: { from: 7, to: 28, step: 1 } },
+ * };
+ * ```
  */
 export interface SweepRequest {
   /** Strategy source code (Java), compiled once and reused by every trial. */
   strategy: string;
-  /** Exchange id, e.g. `binance`. */
+  /** Exchange id, e.g. `binance`, or the reserved value `user` when sweeping against `datasetId`. */
   exchangeId: string;
-  /** Instrument symbol, e.g. `BTC/USDT`. */
-  instrument: string;
+  /** Instrument symbol, e.g. `BTC/USDT`. Exactly one of `instrument`/`datasetId` is required. */
+  instrument?: string;
+  /**
+   * Id of a dataset you uploaded, in place of `instrument`. Exactly one of
+   * `instrument`/`datasetId` is required. Pairs with `exchangeId: 'user'`.
+   */
+  datasetId?: string;
+  /** Optional specific version of `datasetId`; omit to use its current version. Requires `datasetId`. */
+  datasetVersionId?: string;
   /** Range start (ISO-8601, ISO DATE, or BASIC ISO DATE). */
   from: string;
   /** Range end (same formats as `from`; must be later than `from`). */
@@ -655,6 +681,8 @@ export async function sweep(req: SweepRequest, opts: SweepOptions = {}): Promise
  * the same way.
  */
 function validateRequest(req: SweepRequest): void {
+  validatePrepareTarget('sweep', req);
+
   const names = Object.keys(req.params ?? {});
   if (names.length === 0) {
     throw new QTSError('sweep: params must hold at least one axis');
@@ -690,7 +718,9 @@ function prepareData(
   return prepareDataset(
     {
       exchangeId: req.exchangeId,
-      instrument: req.instrument,
+      ...(req.instrument !== undefined ? { instrument: req.instrument } : {}),
+      ...(req.datasetId !== undefined ? { datasetId: req.datasetId } : {}),
+      ...(req.datasetVersionId !== undefined ? { datasetVersionId: req.datasetVersionId } : {}),
       from: req.from,
       to: req.to,
     },