@qtsurfer/sdk 0.6.0 → 0.7.0

package/README.md

@@ -88,7 +88,7 @@ const qts = new QTSurfer({
 
 Orchestrates the full four-step workflow that the raw API exposes:
 
-1. **Compile** the strategy (`POST /strategy` in async mode) and poll `GET /strategy/{id}` until `Completed`.
+1. **Compile** the strategy (`POST /strategy`), which answers synchronously with the `strategyId`.
 2. **Prepare** the data range (`POST /backtest/{exchange}/ticker/prepare`) and poll until `Completed`.
 3. **Execute** the backtest (`POST /backtest/{exchange}/ticker/execute`) and poll `GET /backtest/.../execute/{jobId}` until `Completed`.
 4. Return the `ResultMap` (`pnlTotal`, `totalTrades`, `sharpeRatio`, `signalsUrl`, …).
@@ -173,6 +173,9 @@ Polling, retry, backoff, timeout, and cancellation are delegated to [`cockatiel`
 
 ## Roadmap
 
+Milestone labels below (`v0.1`–`v0.4`) track feature scope, not the npm package's
+semver — see [CHANGELOG.md](./CHANGELOG.md) for the actual release history.
+
 ### v0.1 — Core workflow ✅
 
 - [x] `QTSurfer` client over `@qtsurfer/api-client`
@@ -203,6 +206,9 @@ src/
 ├── index.ts              # public exports
 ├── client.ts             # QTSurfer class
 ├── errors.ts             # QTSError hierarchy
+├── auth/
+│   ├── session.ts        # authenticate() — session bootstrap + JWT refresh on 401
+│   └── tokenStore.ts     # TokenStore contract + default InMemoryTokenStore
 └── workflows/
     ├── backtest.ts       # compile → prepare → execute (cockatiel policies)
     └── downloads.ts      # hourly tickers/klines as Lastra/Parquet blobs

package/dist/index.d.ts

@@ -14,7 +14,15 @@ interface BacktestRequest {
     /** When true, the worker uploads emitted signals to object storage. */
     storeSignals?: boolean;
 }
+/**
+ * Resolved value of the backtest workflow (see {@link QTSurfer.backtest}).
+ * Alias for api-client's `ResultMap` — always includes core fields
+ * (`hostName`, `iops`, `instrument`); yield metrics (`pnlTotal`,
+ * `totalTrades`, `equityCurve`, etc.) are only present once the strategy
+ * has emitted at least one trade.
+ */
 type BacktestResult = ResultMap;
+/** The three sequential stages {@link QTSurfer.backtest} moves through, in order. */
 type BacktestStage = 'compiling' | 'preparing' | 'executing';
 interface BacktestProgress {
     stage: BacktestStage;
@@ -43,22 +51,48 @@ interface BacktestOptions {
 /** Wire format for hourly tickers/klines downloads. */
 type DownloadFormat = 'lastra' | 'parquet';
 
+/** Configuration for {@link QTSurfer}. */
 interface QTSurferOptions {
+    /** Base URL of the QTSurfer API, e.g. `https://api.qtsurfer.com/v1`. */
     baseUrl: string;
+    /**
+     * Pre-obtained bearer token. When omitted, requests go out unauthenticated.
+     * Use the `authenticate()` helper instead of this constructor if you want
+     * the SDK to exchange an apikey for a JWT and refresh it on `401` for you.
+     */
     token?: string;
+    /** Inject a custom `fetch` (Node 20+, browser, or test mock). */
     fetch?: typeof fetch;
 }
+/** Selects one hour of tickers or klines for a single instrument. */
 interface DownloadHourArgs {
+    /** Exchange id, e.g. `binance`. */
     exchangeId: string;
+    /** Base asset of the instrument, e.g. `BTC`. */
     base: string;
+    /** Quote asset of the instrument, e.g. `USDT`. */
     quote: string;
     /** Hour selector in `YYYY-MM-DDTHH` (UTC). */
     hour: string;
     /** Wire format. Defaults to `'lastra'`. */
     format?: DownloadFormat;
 }
+/**
+ * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's
+ * workflow methods (`backtest`, `tickers`, `klines`). 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
+ * this constructor unless you already manage the JWT lifecycle yourself.
+ */
 declare class QTSurfer {
     constructor(options: QTSurferOptions);
+    /**
+     * Run a backtest end-to-end: compile the strategy, prepare the requested
+     * data range, execute it, and resolve with the result once execution
+     * completes. See the underlying `backtest` workflow for the
+     * stage-by-stage error and retry semantics.
+     */
     backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
     /**
      * Download one hour of raw tickers for an instrument as a {@link Blob}.
@@ -69,27 +103,68 @@ declare class QTSurfer {
     klines(args: DownloadHourArgs): Promise<Blob>;
 }
 
+/**
+ * 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.
+ */
 declare class QTSError extends Error {
     readonly cause?: unknown | undefined;
     /** HTTP status code, when the underlying transport surfaced one. */
     readonly status?: number;
     constructor(message: string, cause?: unknown | undefined, status?: number);
 }
+/**
+ * Thrown when strategy compilation fails. A `429` means the source was never
+ * judged — too many compilations were already in flight — and is safe to
+ * retry. Any other status (typically `400`) means the source itself does
+ * not compile, so retrying with the same input fails again.
+ */
 declare class QTSStrategyCompileError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Thrown when the data-preparation stage fails: submitting the prepare
+ * request, polling its status, or a backend-reported preparation failure
+ * (e.g. no data available for the requested range) all surface here.
+ */
 declare class QTSPreparationError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Thrown when the execute stage fails: submitting the execute request,
+ * polling its result, or a backend-reported execution failure all surface
+ * here.
+ */
 declare class QTSExecutionError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Thrown when a stage (prepare or execute) exceeds `timeoutMs`. The stage
+ * may still be running server-side — this only means the SDK stopped
+ * waiting locally — so it is fine to retry, optionally with a larger
+ * `timeoutMs`.
+ */
 declare class QTSTimeoutError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Thrown when a stage is aborted — either because the caller's
+ * `AbortSignal` fired, or because the backend itself reported the
+ * prepare/execute job as aborted. Either way this reflects a deliberate
+ * stop, not a failure, and is not something to retry automatically.
+ */
 declare class QTSCanceledError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Thrown by the tickers/klines download functions on any non-2xx response or
+ * transport failure. Carries the HTTP `status` when one was received: a
+ * `4xx` means the request itself is wrong (bad hour or instrument), while a
+ * `5xx` or a missing status (transport failure) is generally safe to retry.
+ */
 declare class QTSDownloadError extends QTSError {
     constructor(message: string, cause?: unknown, status?: number);
 }
@@ -175,8 +250,18 @@ declare class AuthenticatedClient {
      */
     private withRefreshOn401;
     private applyConfig;
+    /**
+     * Run a backtest end-to-end (compile → prepare → execute), sending the
+     * currently cached token (minting one first if none is cached). Unlike
+     * `tickers()`/`klines()`, a `401` here is not auto-retried: the underlying
+     * stage errors carry no HTTP status, so a token that expires mid-backtest
+     * surfaces as `QTSPreparationError`/`QTSExecutionError` rather than
+     * triggering a refresh.
+     */
     backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+    /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */
     tickers(args: DownloadHourArgs): Promise<Blob>;
+    /** Download one hour of klines. Refreshes the token once on `401` before retrying. */
     klines(args: DownloadHourArgs): Promise<Blob>;
 }
 /**

package/dist/index.js

@@ -7,7 +7,6 @@ import {
   executeBacktest,
   getBacktestResult,
   getPrepareStatus,
-  getStrategy,
   compileStrategy as apiCompileStrategy,
   prepareBacktest
 } from "@qtsurfer/api-client";
@@ -90,7 +89,7 @@ function normalizeStatus(raw) {
 async function backtest(req, opts = {}) {
   const policy = buildStagePolicy(opts);
   opts.onProgress?.({ stage: "compiling" });
-  const strategyId = await compileStrategy(req.strategy, policy, opts);
+  const strategyId = await compileStrategy(req.strategy, opts);
   opts.onProgress?.({ stage: "preparing" });
   const prepareJobId = await prepareData(req, policy, opts);
   opts.onProgress?.({ stage: "executing" });
@@ -112,42 +111,24 @@ function buildStagePolicy(opts) {
   );
   return opts.timeoutMs ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy) : retryPolicy;
 }
-async function compileStrategy(source, policy, opts) {
-  const { data, error } = await apiCompileStrategy({
+async function compileStrategy(source, opts) {
+  const { data, error, response } = await apiCompileStrategy({
     body: source,
-    headers: { "X-Compile-Async": true },
     ...opts.signal ? { signal: opts.signal } : {}
   });
-  if (error) throw new QTSStrategyCompileError("Strategy submission failed", error);
-  if (!data) throw new QTSStrategyCompileError("Empty response from strategy endpoint");
-  if ("strategyId" in data && data.strategyId) {
-    return data.strategyId;
-  }
-  if (!("jobId" in data) || !data.jobId) {
-    throw new QTSStrategyCompileError("Missing jobId/strategyId in compile response");
-  }
-  const compileJobId = data.jobId;
-  const status = await runStage(
-    policy,
-    opts,
-    async ({ signal }) => {
-      const res = await getStrategy({ path: { strategyId: compileJobId }, signal });
-      if (res.error) throw new QTSStrategyCompileError("Compile status request failed", res.error);
-      if (!res.data) throw new QTSStrategyCompileError("Empty compile status response");
-      return res.data;
+  if (error) {
+    if (response?.status === 429) {
+      throw new QTSStrategyCompileError(
+        "Strategy was not compiled, too many compilations in flight; retry later",
+        error
+      );
     }
-  );
-  const norm = normalizeStatus(status.status);
-  if (norm === "failed") {
-    throw new QTSStrategyCompileError(status.statusDetail ?? "Strategy compilation failed");
-  }
-  if (norm === "aborted") {
-    throw new QTSCanceledError("Strategy compilation aborted");
+    throw new QTSStrategyCompileError("Strategy compilation failed", error);
   }
-  if (!status.strategyId) {
-    throw new QTSStrategyCompileError("Compile completed without a strategyId");
+  if (!data?.strategyId) {
+    throw new QTSStrategyCompileError("Compile response missing strategyId");
   }
-  return status.strategyId;
+  return data.strategyId;
 }
 async function prepareData(req, policy, opts) {
   const { data, error } = await prepareBacktest({
@@ -311,6 +292,12 @@ var QTSurfer = class {
       ...options.fetch ? { fetch: options.fetch } : {}
     });
   }
+  /**
+   * Run a backtest end-to-end: compile the strategy, prepare the requested
+   * data range, execute it, and resolve with the result once execution
+   * completes. See the underlying `backtest` workflow for the
+   * stage-by-stage error and retry semantics.
+   */
   backtest(req, opts) {
     return backtest(req, opts);
   }
@@ -439,12 +426,22 @@ var AuthenticatedClient = class {
     });
   }
   // ---- Workflow surface (mirrors QTSurfer) ----
+  /**
+   * Run a backtest end-to-end (compile → prepare → execute), sending the
+   * currently cached token (minting one first if none is cached). Unlike
+   * `tickers()`/`klines()`, a `401` here is not auto-retried: the underlying
+   * stage errors carry no HTTP status, so a token that expires mid-backtest
+   * surfaces as `QTSPreparationError`/`QTSExecutionError` rather than
+   * triggering a refresh.
+   */
   backtest(req, opts) {
     return this.withRefreshOn401(() => backtest(req, opts));
   }
+  /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */
   tickers(args) {
     return this.withRefreshOn401(() => downloadTickers(args));
   }
+  /** Download one hour of klines. Refreshes the token once on `401` before retrying. */
   klines(args) {
     return this.withRefreshOn401(() => downloadKlines(args));
   }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts","../src/workflows/backtest.ts","../src/errors.ts","../src/workflows/downloads.ts","../src/auth/session.ts","../src/auth/tokenStore.ts"],"sourcesContent":["import { client as apiClient } from '@qtsurfer/api-client';\nimport {\n  backtest,\n  type BacktestOptions,\n  type BacktestRequest,\n  type BacktestResult,\n} from './workflows/backtest';\nimport {\n  downloadKlines,\n  downloadTickers,\n  type DownloadFormat,\n} from './workflows/downloads';\n\nexport interface QTSurferOptions {\n  baseUrl: string;\n  token?: string;\n  fetch?: typeof fetch;\n}\n\nexport interface DownloadHourArgs {\n  exchangeId: string;\n  base: string;\n  quote: string;\n  /** Hour selector in `YYYY-MM-DDTHH` (UTC). */\n  hour: string;\n  /** Wire format. Defaults to `'lastra'`. */\n  format?: DownloadFormat;\n}\n\nexport class QTSurfer {\n  constructor(options: QTSurferOptions) {\n    apiClient.setConfig({\n      baseUrl: options.baseUrl,\n      ...(options.token\n        ? { headers: { Authorization: `Bearer ${options.token}` } }\n        : {}),\n      ...(options.fetch ? { fetch: options.fetch } : {}),\n    });\n  }\n\n  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {\n    return backtest(req, opts);\n  }\n\n  /**\n   * Download one hour of raw tickers for an instrument as a {@link Blob}.\n   * Defaults to Lastra; pass `{ format: 'parquet' }` for Parquet.\n   */\n  tickers(args: DownloadHourArgs): Promise<Blob> {\n    return downloadTickers(args);\n  }\n\n  /** Download one hour of klines for an instrument as a {@link Blob}. */\n  klines(args: DownloadHourArgs): Promise<Blob> {\n    return downloadKlines(args);\n  }\n\n  // Future surface:\n  //   strategies: { compile, status, list }\n  //   instruments: { list, get } with TTL cache\n  //   jobs: { cancel, stream, result }\n}\n","import {\n  cancelBacktest,\n  executeBacktest,\n  getBacktestResult,\n  getPrepareStatus,\n  getStrategy,\n  compileStrategy as apiCompileStrategy,\n  prepareBacktest,\n  type DataSourceType,\n  type ResultMap,\n} from '@qtsurfer/api-client';\nimport {\n  ExponentialBackoff,\n  TaskCancelledError,\n  TimeoutStrategy,\n  handleWhenResult,\n  retry,\n  timeout,\n  wrap,\n  type IPolicy,\n  type ICancellationContext,\n} from 'cockatiel';\nimport {\n  QTSCanceledError,\n  QTSExecutionError,\n  QTSPreparationError,\n  QTSStrategyCompileError,\n  QTSTimeoutError,\n} from '../errors';\n\nexport interface BacktestRequest {\n  /** Strategy source code (Java) */\n  strategy: string;\n  /** Exchange id, e.g. `binance` */\n  exchangeId: string;\n  /** Instrument symbol, e.g. `BTC/USDT` */\n  instrument: string;\n  /** Date range start (ISO-8601, ISO DATE or BASIC ISO DATE) */\n  from: string;\n  /** Date range end (same formats as `from`) */\n  to: string;\n  /** When true, the worker uploads emitted signals to object storage. */\n  storeSignals?: boolean;\n}\n\nexport type BacktestResult = ResultMap;\n\nexport type BacktestStage = 'compiling' | 'preparing' | 'executing';\n\nexport interface BacktestProgress {\n  stage: BacktestStage;\n  /** 0-100 when size is known. Undefined during stage start. */\n  percent?: number;\n  /**\n   * Fraction (0-1) of the requested prepare window that actually holds data,\n   * reported by the backend once preparation completes. Present only on the\n   * final `preparing` event.\n   */\n  coverageRatio?: number;\n}\n\nexport interface BacktestOptions {\n  /** Abort the workflow. Cancels the current poll and calls `cancelBacktest` server-side if execution has started. */\n  signal?: AbortSignal;\n  /** Called on stage transitions and after each poll with updated progress. */\n  onProgress?: (p: BacktestProgress) => void;\n  /** Initial interval between polls. Default 500ms, backed off up to `maxPollIntervalMs`. */\n  pollIntervalMs?: number;\n  /** Upper bound for exponential backoff. Default 5000ms. */\n  maxPollIntervalMs?: number;\n  /** Per-stage timeout. Default none. */\n  timeoutMs?: number;\n}\n\nconst TICKER: DataSourceType = 'ticker';\n\ntype JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';\n\n/**\n * Normalize the backend job status to a stable lowercase form so we can\n * reason about it regardless of OpenAPI spec drift (the live API sometimes\n * returns lowercase values like `queued` / `completed` / `failed`).\n */\ntype NormalizedStatus = 'in-progress' | 'completed' | 'failed' | 'aborted';\n\nfunction normalizeStatus(raw: unknown): NormalizedStatus {\n  const value = typeof raw === 'string' ? raw.toLowerCase() : '';\n  if (value === 'completed') return 'completed';\n  if (value === 'failed') return 'failed';\n  if (value === 'aborted' || value === 'cancelled' || value === 'canceled') {\n    return 'aborted';\n  }\n  // new / started / queued / running / anything else → still running\n  return 'in-progress';\n}\n\nexport async function backtest(\n  req: BacktestRequest,\n  opts: BacktestOptions = {},\n): Promise<BacktestResult> {\n  const policy = buildStagePolicy(opts);\n\n  // 1. Compile strategy (async mode)\n  opts.onProgress?.({ stage: 'compiling' });\n  const strategyId = await compileStrategy(req.strategy, policy, opts);\n\n  // 2. Prepare data\n  opts.onProgress?.({ stage: 'preparing' });\n  const prepareJobId = await prepareData(req, policy, opts);\n\n  // 3. Execute\n  opts.onProgress?.({ stage: 'executing' });\n  return executeStrategy(req, prepareJobId, strategyId, policy, opts);\n}\n\nfunction buildStagePolicy(opts: BacktestOptions): IPolicy<ICancellationContext, never> {\n  const retryPolicy = retry(\n    handleWhenResult((r) => {\n      const status = (r as { status?: unknown } | undefined)?.status;\n      return normalizeStatus(status) === 'in-progress';\n    }),\n    {\n      maxAttempts: Number.MAX_SAFE_INTEGER,\n      backoff: new ExponentialBackoff({\n        initialDelay: opts.pollIntervalMs ?? 500,\n        maxDelay: opts.maxPollIntervalMs ?? 5000,\n      }),\n    },\n  );\n\n  return opts.timeoutMs\n    ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)\n    : retryPolicy;\n}\n\nasync function compileStrategy(\n  source: string,\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n): Promise<string> {\n  const { data, error } = await apiCompileStrategy({\n    body: source,\n    headers: { 'X-Compile-Async': true },\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n  if (error) throw new QTSStrategyCompileError('Strategy submission failed', error);\n  if (!data) throw new QTSStrategyCompileError('Empty response from strategy endpoint');\n\n  // Sync mode returns { strategyId }; async mode returns { jobId }.\n  if ('strategyId' in data && data.strategyId) {\n    return data.strategyId;\n  }\n  if (!('jobId' in data) || !data.jobId) {\n    throw new QTSStrategyCompileError('Missing jobId/strategyId in compile response');\n  }\n\n  const compileJobId = data.jobId;\n  const status = await runStage(\n    policy,\n    opts,\n    async ({ signal }) => {\n      const res = await getStrategy({ path: { strategyId: compileJobId }, signal });\n      if (res.error) throw new QTSStrategyCompileError('Compile status request failed', res.error);\n      if (!res.data) throw new QTSStrategyCompileError('Empty compile status response');\n      return res.data;\n    },\n  );\n\n  const norm = normalizeStatus(status.status);\n  if (norm === 'failed') {\n    throw new QTSStrategyCompileError(status.statusDetail ?? 'Strategy compilation failed');\n  }\n  if (norm === 'aborted') {\n    throw new QTSCanceledError('Strategy compilation aborted');\n  }\n  if (!status.strategyId) {\n    throw new QTSStrategyCompileError('Compile completed without a strategyId');\n  }\n  return status.strategyId;\n}\n\nasync function prepareData(\n  req: BacktestRequest,\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n): Promise<string> {\n  const { data, error } = await prepareBacktest({\n    path: { exchangeId: req.exchangeId, type: TICKER },\n    body: { instrument: req.instrument, from: req.from, to: req.to },\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n  if (error) throw new QTSPreparationError('Prepare submission failed', error);\n  if (!data?.jobId) throw new QTSPreparationError('Missing jobId in prepare response');\n\n  const prepareJobId = data.jobId;\n  const state = await runStage(\n    policy,\n    opts,\n    async ({ signal }) => {\n      const res = await getPrepareStatus({\n        path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },\n        signal,\n      });\n      if (res.error) throw new QTSPreparationError('Preparation status request failed', res.error);\n      if (!res.data) throw new QTSPreparationError('Empty preparation status response');\n      return res.data;\n    },\n    (r) => {\n      if (r.size > 0) {\n        opts.onProgress?.({ stage: 'preparing', percent: (r.completed / r.size) * 100 });\n      }\n    },\n  );\n\n  const prepNorm = normalizeStatus(state.status);\n  if (prepNorm === 'failed') {\n    throw new QTSPreparationError(state.statusDetail ?? 'Data preparation failed');\n  }\n  if (prepNorm === 'aborted') {\n    throw new QTSCanceledError('Data preparation aborted');\n  }\n  // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the\n  // final preparing event, so callers can react to a partially-covered range.\n  opts.onProgress?.({ stage: 'preparing', percent: 100, coverageRatio: state.coverageRatio });\n  return prepareJobId;\n}\n\nasync function executeStrategy(\n  req: BacktestRequest,\n  prepareJobId: string,\n  strategyId: string,\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n): Promise<BacktestResult> {\n  const { data, error } = await executeBacktest({\n    path: { exchangeId: req.exchangeId, type: TICKER },\n    body: {\n      prepareJobId,\n      strategyId,\n      ...(req.storeSignals !== undefined ? { storeSignals: req.storeSignals } : {}),\n    },\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n  if (error) throw new QTSExecutionError('Execute submission failed', error);\n  if (!data?.jobId) throw new QTSExecutionError('Missing jobId in execute response');\n\n  const executeJobId = data.jobId;\n\n  try {\n    const finalResult = await runStage(\n      policy,\n      opts,\n      async ({ signal }) => {\n        const res = await getBacktestResult({\n          path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },\n          signal,\n        });\n        if (res.error) throw new QTSExecutionError('Execution result request failed', res.error);\n        if (!res.data) throw new QTSExecutionError('Empty execution result response');\n        return { ...res.data.state, __result: res.data.results };\n      },\n      (r) => {\n        if (r.size > 0) {\n          opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });\n        }\n      },\n    );\n\n    const execNorm = normalizeStatus(finalResult.status);\n    if (execNorm === 'failed') {\n      throw new QTSExecutionError(finalResult.statusDetail ?? 'Execution failed');\n    }\n    if (execNorm === 'aborted') {\n      throw new QTSCanceledError('Execution aborted');\n    }\n    return finalResult.__result;\n  } catch (err) {\n    if (err instanceof QTSCanceledError) {\n      await cancelBacktest({\n        path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },\n      }).catch(() => undefined);\n    }\n    throw err;\n  }\n}\n\nasync function runStage<T extends { status: JobStatus }>(\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n  fetchFn: (ctx: ICancellationContext) => Promise<T>,\n  onEachAttempt?: (r: T) => void,\n): Promise<T> {\n  try {\n    return await policy.execute(async (ctx) => {\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');\n      const result = await fetchFn(ctx);\n      onEachAttempt?.(result);\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');\n      return result;\n    }, opts.signal);\n  } catch (err) {\n    if (err instanceof QTSCanceledError) throw err;\n    if (err instanceof TaskCancelledError) {\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);\n      throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);\n    }\n    if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);\n    throw err;\n  }\n}\n","export class QTSError extends Error {\n  /** HTTP status code, when the underlying transport surfaced one. */\n  readonly status?: number;\n  constructor(message: string, readonly cause?: unknown, status?: number) {\n    super(message);\n    this.name = 'QTSError';\n    if (status !== undefined) this.status = status;\n  }\n}\n\nexport class QTSStrategyCompileError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSStrategyCompileError';\n  }\n}\n\nexport class QTSPreparationError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSPreparationError';\n  }\n}\n\nexport class QTSExecutionError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSExecutionError';\n  }\n}\n\nexport class QTSTimeoutError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSTimeoutError';\n  }\n}\n\nexport class QTSCanceledError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSCanceledError';\n  }\n}\n\nexport class QTSDownloadError extends QTSError {\n  constructor(message: string, cause?: unknown, status?: number) {\n    super(message, cause, status);\n    this.name = 'QTSDownloadError';\n  }\n}\n\n/**\n * Thrown by the `authenticate()` helper when the apikey is missing or the JWT\n * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).\n */\nexport class QTSAuthError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSAuthError';\n  }\n}\n","import {\n  downloadKlines as apiDownloadKlines,\n  downloadTickers as apiDownloadTickers,\n} from '@qtsurfer/api-client';\nimport { QTSDownloadError } from '../errors';\n\n/** Wire format for hourly tickers/klines downloads. */\nexport type DownloadFormat = 'lastra' | 'parquet';\n\nexport interface DownloadParams {\n  exchangeId: string;\n  base: string;\n  quote: string;\n  /** Hour selector in `YYYY-MM-DDTHH` (UTC). */\n  hour: string;\n  /** Defaults to {@code 'lastra'}. */\n  format?: DownloadFormat;\n}\n\n/**\n * Download one hour of raw tickers as a {@link Blob}.\n *\n * The default wire format is Lastra (`application/vnd.lastra`); pass\n * `format: 'parquet'` for on-the-fly Parquet conversion.\n *\n * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure.\n */\nexport async function downloadTickers(params: DownloadParams): Promise<Blob> {\n  const { exchangeId, base, quote, hour, format } = params;\n  const { data, error, response } = await apiDownloadTickers({\n    path: { exchangeId, base, quote },\n    query: { hour, ...(format ? { format } : {}) },\n  });\n  if (error) {\n    throw new QTSDownloadError(\n      `tickers download failed: HTTP ${response.status} — ${describe(error)}`,\n      error,\n      response.status,\n    );\n  }\n  return data as Blob;\n}\n\n/**\n * Download one hour of klines as a {@link Blob}. See {@link downloadTickers}\n * for semantics.\n *\n * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure.\n */\nexport async function downloadKlines(params: DownloadParams): Promise<Blob> {\n  const { exchangeId, base, quote, hour, format } = params;\n  const { data, error, response } = await apiDownloadKlines({\n    path: { exchangeId, base, quote },\n    query: { hour, ...(format ? { format } : {}) },\n  });\n  if (error) {\n    throw new QTSDownloadError(\n      `klines download failed: HTTP ${response.status} — ${describe(error)}`,\n      error,\n      response.status,\n    );\n  }\n  return data as Blob;\n}\n\nfunction describe(error: unknown): string {\n  if (error && typeof error === 'object') {\n    const e = error as { code?: unknown; message?: unknown };\n    const code = typeof e.code === 'string' ? e.code : undefined;\n    const message = typeof e.message === 'string' ? e.message : undefined;\n    if (code && message) return `${code}: ${message}`;\n    if (message) return message;\n    if (code) return code;\n  }\n  return String(error);\n}\n","import {\n  authenticate as apiAuth,\n  client as apiClient,\n  type AuthTokenResponse,\n} from '@qtsurfer/api-client';\nimport { QTSAuthError } from '../errors';\nimport {\n  backtest as runBacktest,\n  type BacktestOptions,\n  type BacktestRequest,\n  type BacktestResult,\n} from '../workflows/backtest';\nimport {\n  downloadKlines,\n  downloadTickers,\n} from '../workflows/downloads';\nimport type { DownloadHourArgs } from '../client';\nimport { InMemoryTokenStore, type TokenStore } from './tokenStore';\n\nconst APIKEY_ENV_VAR = 'QTSURFER_APIKEY';\nconst DEFAULT_BASE_URL = 'https://api.qtsurfer.com/v1';\n\nexport interface AuthOptions {\n  /** Base URL of the QTSurfer API. Defaults to the public production endpoint. */\n  baseUrl?: string;\n  /** Custom token store. Defaults to {@link InMemoryTokenStore}. */\n  store?: TokenStore;\n  /** Inject a custom `fetch` (Node 20+, browser, or test mock). */\n  fetch?: typeof fetch;\n}\n\n/**\n * Authenticated SDK session.\n *\n * Returned by {@link authenticate}. Wraps the underlying api-client, owns a JWT\n * (in memory by default, or in the provided {@link TokenStore}), and\n * transparently re-exchanges the apikey for a fresh JWT on 401.\n *\n * Multi-session note: the session mutates the api-client singleton config\n * on every call. Concurrent sessions in the same process will race; today\n * the SDK targets the one-session-per-process pattern.\n */\nexport class AuthenticatedClient {\n  readonly baseUrl: string;\n  private readonly apikey: string;\n  private readonly store: TokenStore;\n  private readonly fetchImpl: typeof fetch | undefined;\n  private cached: AuthTokenResponse | null = null;\n  private refreshing: Promise<AuthTokenResponse> | null = null;\n\n  constructor(apikey: string, opts: AuthOptions = {}) {\n    this.apikey = apikey;\n    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;\n    this.store = opts.store ?? new InMemoryTokenStore();\n    this.fetchImpl = opts.fetch;\n  }\n\n  /** Currently cached token, if any. */\n  get token(): AuthTokenResponse | null {\n    return this.cached;\n  }\n\n  /** Force a fresh JWT exchange. Bypasses the cache. */\n  async refresh(): Promise<AuthTokenResponse> {\n    if (this.refreshing) return this.refreshing;\n    this.refreshing = (async () => {\n      const { data, error, response } = await apiAuth({\n        baseUrl: this.baseUrl,\n        headers: { 'X-API-Key': this.apikey },\n        ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),\n      });\n      if (error || !data) {\n        throw new QTSAuthError(\n          `authenticate() failed: HTTP ${response.status}`,\n          error,\n        );\n      }\n      this.cached = data;\n      await this.store.save(data);\n      return data;\n    })();\n    try {\n      return await this.refreshing;\n    } finally {\n      this.refreshing = null;\n    }\n  }\n\n  /**\n   * Load a previously-persisted token from the store. If none, mint one.\n   * Called automatically by every workflow method.\n   */\n  async ensureToken(): Promise<AuthTokenResponse> {\n    if (this.cached) return this.cached;\n    const stored = await this.store.load();\n    if (stored) {\n      this.cached = stored;\n      return stored;\n    }\n    return this.refresh();\n  }\n\n  /** Drop the cached token (in memory and in the store). */\n  async clear(): Promise<void> {\n    this.cached = null;\n    await this.store.clear();\n  }\n\n  /**\n   * Run a call with the Bearer header pre-set; if it returns 401, refresh\n   * once and retry. A second 401 surfaces to the caller.\n   */\n  private async withRefreshOn401<T>(call: () => Promise<T>): Promise<T> {\n    await this.applyConfig();\n    try {\n      return await call();\n    } catch (err) {\n      if (!isUnauthorized(err)) throw err;\n      this.cached = null;\n      await this.refresh();\n      await this.applyConfig();\n      return call();\n    }\n  }\n\n  private async applyConfig(): Promise<void> {\n    const token = await this.ensureToken();\n    apiClient.setConfig({\n      baseUrl: this.baseUrl,\n      headers: { Authorization: `Bearer ${token.access_token}` },\n      ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),\n    });\n  }\n\n  // ---- Workflow surface (mirrors QTSurfer) ----\n\n  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {\n    return this.withRefreshOn401(() => runBacktest(req, opts));\n  }\n\n  tickers(args: DownloadHourArgs): Promise<Blob> {\n    return this.withRefreshOn401(() => downloadTickers(args));\n  }\n\n  klines(args: DownloadHourArgs): Promise<Blob> {\n    return this.withRefreshOn401(() => downloadKlines(args));\n  }\n}\n\n/**\n * Exchange a long-lived API key for an authenticated session.\n *\n * If `apikey` is omitted, the SDK reads `QTSURFER_APIKEY` from the\n * environment. The returned {@link AuthenticatedClient} caches the JWT,\n * refreshes it on 401, and exposes the same workflow surface as\n * `QTSurfer` (`backtest`, `tickers`, `klines`).\n *\n * @throws {QTSAuthError} if no apikey is supplied or available in env.\n */\nexport async function authenticate(\n  apikey?: string,\n  opts: AuthOptions = {},\n): Promise<AuthenticatedClient> {\n  const resolved = apikey ?? readEnvApikey();\n  if (!resolved) {\n    throw new QTSAuthError(\n      `authenticate() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`,\n    );\n  }\n  const session = new AuthenticatedClient(resolved, opts);\n  await session.ensureToken();\n  return session;\n}\n\nfunction readEnvApikey(): string | undefined {\n  // `process` is undefined in browser bundlers; guard explicitly.\n  if (typeof process === 'undefined' || !process.env) return undefined;\n  const value = process.env[APIKEY_ENV_VAR];\n  return value && value.length > 0 ? value : undefined;\n}\n\nfunction isUnauthorized(err: unknown): boolean {\n  if (!err || typeof err !== 'object') return false;\n  // SDK-thrown errors (QTSDownloadError, etc.) carry the HTTP status on\n  // a top-level `status` field. Workflow errors that don't yet expose\n  // status default to non-401.\n  const maybeStatus = (err as { status?: unknown }).status;\n  if (typeof maybeStatus === 'number' && maybeStatus === 401) return true;\n  return false;\n}\n","import type { AuthTokenResponse } from '@qtsurfer/api-client';\n\n/**\n * Pluggable token persistence interface.\n *\n * The SDK ships an {@link InMemoryTokenStore} by default. Adopters can\n * implement this contract to back tokens by browser `localStorage`, an\n * on-disk file, a secret manager, etc.\n *\n * The SDK calls {@link load} once per session-startup to seed a cached\n * token (if any), {@link save} after every successful `authenticate()` / refresh,\n * and {@link clear} when the session is explicitly invalidated.\n */\nexport interface TokenStore {\n  /** Return the previously persisted token, or `null` if none. */\n  load(): AuthTokenResponse | null | Promise<AuthTokenResponse | null>;\n  /** Persist the token returned by `POST /v1/auth/token`. */\n  save(token: AuthTokenResponse): void | Promise<void>;\n  /** Drop any persisted token. */\n  clear(): void | Promise<void>;\n}\n\n/**\n * Default {@link TokenStore} — holds the token in a single in-memory slot.\n * Lost on process exit. Sufficient for short-lived scripts and tests.\n */\nexport class InMemoryTokenStore implements TokenStore {\n  private token: AuthTokenResponse | null = null;\n\n  load(): AuthTokenResponse | null {\n    return this.token;\n  }\n\n  save(token: AuthTokenResponse): void {\n    this.token = token;\n  }\n\n  clear(): void {\n    this.token = null;\n  }\n}\n"],"mappings":"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","names":["apiClient","apiClient"]}
+{"version":3,"sources":["../src/client.ts","../src/workflows/backtest.ts","../src/errors.ts","../src/workflows/downloads.ts","../src/auth/session.ts","../src/auth/tokenStore.ts"],"sourcesContent":["import { client as apiClient } from '@qtsurfer/api-client';\nimport {\n  backtest,\n  type BacktestOptions,\n  type BacktestRequest,\n  type BacktestResult,\n} from './workflows/backtest';\nimport {\n  downloadKlines,\n  downloadTickers,\n  type DownloadFormat,\n} from './workflows/downloads';\n\n/** Configuration for {@link QTSurfer}. */\nexport interface QTSurferOptions {\n  /** Base URL of the QTSurfer API, e.g. `https://api.qtsurfer.com/v1`. */\n  baseUrl: string;\n  /**\n   * Pre-obtained bearer token. When omitted, requests go out unauthenticated.\n   * Use the `authenticate()` helper instead of this constructor if you want\n   * the SDK to exchange an apikey for a JWT and refresh it on `401` for you.\n   */\n  token?: string;\n  /** Inject a custom `fetch` (Node 20+, browser, or test mock). */\n  fetch?: typeof fetch;\n}\n\n/** Selects one hour of tickers or klines for a single instrument. */\nexport interface DownloadHourArgs {\n  /** Exchange id, e.g. `binance`. */\n  exchangeId: string;\n  /** Base asset of the instrument, e.g. `BTC`. */\n  base: string;\n  /** Quote asset of the instrument, e.g. `USDT`. */\n  quote: string;\n  /** Hour selector in `YYYY-MM-DDTHH` (UTC). */\n  hour: string;\n  /** Wire format. Defaults to `'lastra'`. */\n  format?: DownloadFormat;\n}\n\n/**\n * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's\n * workflow methods (`backtest`, `tickers`, `klines`). Constructing an\n * instance reconfigures the underlying api-client singleton, so avoid\n * holding two `QTSurfer`s with different `baseUrl`s or tokens alive in the\n * same process — they will race. Prefer the `authenticate()` helper over\n * this constructor unless you already manage the JWT lifecycle yourself.\n */\nexport class QTSurfer {\n  constructor(options: QTSurferOptions) {\n    apiClient.setConfig({\n      baseUrl: options.baseUrl,\n      ...(options.token\n        ? { headers: { Authorization: `Bearer ${options.token}` } }\n        : {}),\n      ...(options.fetch ? { fetch: options.fetch } : {}),\n    });\n  }\n\n  /**\n   * Run a backtest end-to-end: compile the strategy, prepare the requested\n   * data range, execute it, and resolve with the result once execution\n   * completes. See the underlying `backtest` workflow for the\n   * stage-by-stage error and retry semantics.\n   */\n  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {\n    return backtest(req, opts);\n  }\n\n  /**\n   * Download one hour of raw tickers for an instrument as a {@link Blob}.\n   * Defaults to Lastra; pass `{ format: 'parquet' }` for Parquet.\n   */\n  tickers(args: DownloadHourArgs): Promise<Blob> {\n    return downloadTickers(args);\n  }\n\n  /** Download one hour of klines for an instrument as a {@link Blob}. */\n  klines(args: DownloadHourArgs): Promise<Blob> {\n    return downloadKlines(args);\n  }\n\n  // Future surface:\n  //   strategies: { compile, status, list }\n  //   instruments: { list, get } with TTL cache\n  //   jobs: { cancel, stream, result }\n}\n","import {\n  cancelBacktest,\n  executeBacktest,\n  getBacktestResult,\n  getPrepareStatus,\n  compileStrategy as apiCompileStrategy,\n  prepareBacktest,\n  type DataSourceType,\n  type ResultMap,\n} from '@qtsurfer/api-client';\nimport {\n  ExponentialBackoff,\n  TaskCancelledError,\n  TimeoutStrategy,\n  handleWhenResult,\n  retry,\n  timeout,\n  wrap,\n  type IPolicy,\n  type ICancellationContext,\n} from 'cockatiel';\nimport {\n  QTSCanceledError,\n  QTSExecutionError,\n  QTSPreparationError,\n  QTSStrategyCompileError,\n  QTSTimeoutError,\n} from '../errors';\n\nexport interface BacktestRequest {\n  /** Strategy source code (Java) */\n  strategy: string;\n  /** Exchange id, e.g. `binance` */\n  exchangeId: string;\n  /** Instrument symbol, e.g. `BTC/USDT` */\n  instrument: string;\n  /** Date range start (ISO-8601, ISO DATE or BASIC ISO DATE) */\n  from: string;\n  /** Date range end (same formats as `from`) */\n  to: string;\n  /** When true, the worker uploads emitted signals to object storage. */\n  storeSignals?: boolean;\n}\n\n/**\n * Resolved value of the backtest workflow (see {@link QTSurfer.backtest}).\n * Alias for api-client's `ResultMap` — always includes core fields\n * (`hostName`, `iops`, `instrument`); yield metrics (`pnlTotal`,\n * `totalTrades`, `equityCurve`, etc.) are only present once the strategy\n * has emitted at least one trade.\n */\nexport type BacktestResult = ResultMap;\n\n/** The three sequential stages {@link QTSurfer.backtest} moves through, in order. */\nexport type BacktestStage = 'compiling' | 'preparing' | 'executing';\n\nexport interface BacktestProgress {\n  stage: BacktestStage;\n  /** 0-100 when size is known. Undefined during stage start. */\n  percent?: number;\n  /**\n   * Fraction (0-1) of the requested prepare window that actually holds data,\n   * reported by the backend once preparation completes. Present only on the\n   * final `preparing` event.\n   */\n  coverageRatio?: number;\n}\n\nexport interface BacktestOptions {\n  /** Abort the workflow. Cancels the current poll and calls `cancelBacktest` server-side if execution has started. */\n  signal?: AbortSignal;\n  /** Called on stage transitions and after each poll with updated progress. */\n  onProgress?: (p: BacktestProgress) => void;\n  /** Initial interval between polls. Default 500ms, backed off up to `maxPollIntervalMs`. */\n  pollIntervalMs?: number;\n  /** Upper bound for exponential backoff. Default 5000ms. */\n  maxPollIntervalMs?: number;\n  /** Per-stage timeout. Default none. */\n  timeoutMs?: number;\n}\n\nconst TICKER: DataSourceType = 'ticker';\n\ntype JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';\n\n/**\n * Normalize the backend job status to a stable lowercase form so we can\n * reason about it regardless of OpenAPI spec drift (the live API sometimes\n * returns lowercase values like `queued` / `completed` / `failed`).\n *\n * Only the three terminal statuses end a poll loop. Everything else — including a\n * **missing** status — means \"keep asking\": the API answers `202` with an empty body when a\n * job is known but its result is not readable yet, and that response carries no state at all.\n * Mapping absent to in-progress is what makes a 202 continue the loop under its timeout\n * instead of being mistaken for a finished job with no data.\n */\ntype NormalizedStatus = 'in-progress' | 'completed' | 'failed' | 'aborted';\n\nfunction normalizeStatus(raw: unknown): NormalizedStatus {\n  const value = typeof raw === 'string' ? raw.toLowerCase() : '';\n  if (value === 'completed') return 'completed';\n  if (value === 'failed') return 'failed';\n  if (value === 'aborted' || value === 'cancelled' || value === 'canceled') {\n    return 'aborted';\n  }\n  // new / started / queued / running / absent (202) / anything else → still running\n  return 'in-progress';\n}\n\nexport async function backtest(\n  req: BacktestRequest,\n  opts: BacktestOptions = {},\n): Promise<BacktestResult> {\n  const policy = buildStagePolicy(opts);\n\n  // 1. Compile strategy (single synchronous request)\n  opts.onProgress?.({ stage: 'compiling' });\n  const strategyId = await compileStrategy(req.strategy, opts);\n\n  // 2. Prepare data\n  opts.onProgress?.({ stage: 'preparing' });\n  const prepareJobId = await prepareData(req, policy, opts);\n\n  // 3. Execute\n  opts.onProgress?.({ stage: 'executing' });\n  return executeStrategy(req, prepareJobId, strategyId, policy, opts);\n}\n\nfunction buildStagePolicy(opts: BacktestOptions): IPolicy<ICancellationContext, never> {\n  const retryPolicy = retry(\n    handleWhenResult((r) => {\n      const status = (r as { status?: unknown } | undefined)?.status;\n      return normalizeStatus(status) === 'in-progress';\n    }),\n    {\n      maxAttempts: Number.MAX_SAFE_INTEGER,\n      backoff: new ExponentialBackoff({\n        initialDelay: opts.pollIntervalMs ?? 500,\n        maxDelay: opts.maxPollIntervalMs ?? 5000,\n      }),\n    },\n  );\n\n  return opts.timeoutMs\n    ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)\n    : retryPolicy;\n}\n\n/**\n * Compile in a single request: the API answers synchronously with the `strategyId`,\n * so there is no job to poll. A compile error arrives here as a `400`, not on a later poll.\n */\nasync function compileStrategy(source: string, opts: BacktestOptions): Promise<string> {\n  const { data, error, response } = await apiCompileStrategy({\n    body: source,\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n\n  if (error) {\n    // A 429 means the platform is holding too many compilations at once and the source was never\n    // judged — worth separating from the 400 that says the source itself does not compile.\n    // Read the status inside this branch and optionally: a transport failure carries no response,\n    // and dereferencing one would raise a TypeError that buries the error actually being reported.\n    if (response?.status === 429) {\n      throw new QTSStrategyCompileError(\n        'Strategy was not compiled, too many compilations in flight; retry later',\n        error,\n      );\n    }\n    throw new QTSStrategyCompileError('Strategy compilation failed', error);\n  }\n  if (!data?.strategyId) {\n    throw new QTSStrategyCompileError('Compile response missing strategyId');\n  }\n  return data.strategyId;\n}\n\nasync function prepareData(\n  req: BacktestRequest,\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n): Promise<string> {\n  const { data, error } = await prepareBacktest({\n    path: { exchangeId: req.exchangeId, type: TICKER },\n    body: { instrument: req.instrument, from: req.from, to: req.to },\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n  if (error) throw new QTSPreparationError('Prepare submission failed', error);\n  if (!data?.jobId) throw new QTSPreparationError('Missing jobId in prepare response');\n\n  const prepareJobId = data.jobId;\n  const state = await runStage(\n    policy,\n    opts,\n    async ({ signal }) => {\n      const res = await getPrepareStatus({\n        path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },\n        signal,\n      });\n      if (res.error) throw new QTSPreparationError('Preparation status request failed', res.error);\n      if (!res.data) throw new QTSPreparationError('Empty preparation status response');\n      return res.data;\n    },\n    (r) => {\n      if (r.size > 0) {\n        opts.onProgress?.({ stage: 'preparing', percent: (r.completed / r.size) * 100 });\n      }\n    },\n  );\n\n  const prepNorm = normalizeStatus(state.status);\n  if (prepNorm === 'failed') {\n    throw new QTSPreparationError(state.statusDetail ?? 'Data preparation failed');\n  }\n  if (prepNorm === 'aborted') {\n    throw new QTSCanceledError('Data preparation aborted');\n  }\n  // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the\n  // final preparing event, so callers can react to a partially-covered range.\n  opts.onProgress?.({ stage: 'preparing', percent: 100, coverageRatio: state.coverageRatio });\n  return prepareJobId;\n}\n\nasync function executeStrategy(\n  req: BacktestRequest,\n  prepareJobId: string,\n  strategyId: string,\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n): Promise<BacktestResult> {\n  const { data, error } = await executeBacktest({\n    path: { exchangeId: req.exchangeId, type: TICKER },\n    body: {\n      prepareJobId,\n      strategyId,\n      ...(req.storeSignals !== undefined ? { storeSignals: req.storeSignals } : {}),\n    },\n    ...(opts.signal ? { signal: opts.signal } : {}),\n  });\n  if (error) throw new QTSExecutionError('Execute submission failed', error);\n  if (!data?.jobId) throw new QTSExecutionError('Missing jobId in execute response');\n\n  const executeJobId = data.jobId;\n\n  try {\n    const finalResult = await runStage(\n      policy,\n      opts,\n      async ({ signal }) => {\n        const res = await getBacktestResult({\n          path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },\n          signal,\n        });\n        if (res.error) throw new QTSExecutionError('Execution result request failed', res.error);\n        if (!res.data) throw new QTSExecutionError('Empty execution result response');\n        // A 202 carries an empty body: no `state`, so the spread yields an undefined status and\n        // the retry predicate keeps polling. That is the intended handling, not a coincidence —\n        // see normalizeStatus. Do not \"fix\" this into a throw or an early return of the result.\n        return { ...res.data.state, __result: res.data.results };\n      },\n      (r) => {\n        if (r.size > 0) {\n          opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });\n        }\n      },\n    );\n\n    const execNorm = normalizeStatus(finalResult.status);\n    if (execNorm === 'failed') {\n      throw new QTSExecutionError(finalResult.statusDetail ?? 'Execution failed');\n    }\n    if (execNorm === 'aborted') {\n      throw new QTSCanceledError('Execution aborted');\n    }\n    return finalResult.__result;\n  } catch (err) {\n    if (err instanceof QTSCanceledError) {\n      await cancelBacktest({\n        path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },\n      }).catch(() => undefined);\n    }\n    throw err;\n  }\n}\n\nasync function runStage<T extends { status: JobStatus }>(\n  policy: IPolicy<ICancellationContext, never>,\n  opts: BacktestOptions,\n  fetchFn: (ctx: ICancellationContext) => Promise<T>,\n  onEachAttempt?: (r: T) => void,\n): Promise<T> {\n  try {\n    return await policy.execute(async (ctx) => {\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');\n      const result = await fetchFn(ctx);\n      onEachAttempt?.(result);\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted');\n      return result;\n    }, opts.signal);\n  } catch (err) {\n    if (err instanceof QTSCanceledError) throw err;\n    if (err instanceof TaskCancelledError) {\n      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);\n      throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);\n    }\n    if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);\n    throw err;\n  }\n}\n","/**\n * Base class for every error the SDK throws. Catch this to handle all SDK\n * failures generically, or catch a specific subclass below to tell which\n * stage failed. `status` is only set when the throw site had an HTTP status\n * to attach — today that is just {@link QTSDownloadError}; the workflow-stage\n * errors carry `cause` instead and encode retryability in their message.\n */\nexport class QTSError extends Error {\n  /** HTTP status code, when the underlying transport surfaced one. */\n  readonly status?: number;\n  constructor(message: string, readonly cause?: unknown, status?: number) {\n    super(message);\n    this.name = 'QTSError';\n    if (status !== undefined) this.status = status;\n  }\n}\n\n/**\n * Thrown when strategy compilation fails. A `429` means the source was never\n * judged — too many compilations were already in flight — and is safe to\n * retry. Any other status (typically `400`) means the source itself does\n * not compile, so retrying with the same input fails again.\n */\nexport class QTSStrategyCompileError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSStrategyCompileError';\n  }\n}\n\n/**\n * Thrown when the data-preparation stage fails: submitting the prepare\n * request, polling its status, or a backend-reported preparation failure\n * (e.g. no data available for the requested range) all surface here.\n */\nexport class QTSPreparationError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSPreparationError';\n  }\n}\n\n/**\n * Thrown when the execute stage fails: submitting the execute request,\n * polling its result, or a backend-reported execution failure all surface\n * here.\n */\nexport class QTSExecutionError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSExecutionError';\n  }\n}\n\n/**\n * Thrown when a stage (prepare or execute) exceeds `timeoutMs`. The stage\n * may still be running server-side — this only means the SDK stopped\n * waiting locally — so it is fine to retry, optionally with a larger\n * `timeoutMs`.\n */\nexport class QTSTimeoutError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSTimeoutError';\n  }\n}\n\n/**\n * Thrown when a stage is aborted — either because the caller's\n * `AbortSignal` fired, or because the backend itself reported the\n * prepare/execute job as aborted. Either way this reflects a deliberate\n * stop, not a failure, and is not something to retry automatically.\n */\nexport class QTSCanceledError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSCanceledError';\n  }\n}\n\n/**\n * Thrown by the tickers/klines download functions on any non-2xx response or\n * transport failure. Carries the HTTP `status` when one was received: a\n * `4xx` means the request itself is wrong (bad hour or instrument), while a\n * `5xx` or a missing status (transport failure) is generally safe to retry.\n */\nexport class QTSDownloadError extends QTSError {\n  constructor(message: string, cause?: unknown, status?: number) {\n    super(message, cause, status);\n    this.name = 'QTSDownloadError';\n  }\n}\n\n/**\n * Thrown by the `authenticate()` helper when the apikey is missing or the JWT\n * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).\n */\nexport class QTSAuthError extends QTSError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = 'QTSAuthError';\n  }\n}\n","import {\n  downloadKlines as apiDownloadKlines,\n  downloadTickers as apiDownloadTickers,\n} from '@qtsurfer/api-client';\nimport { QTSDownloadError } from '../errors';\n\n/** Wire format for hourly tickers/klines downloads. */\nexport type DownloadFormat = 'lastra' | 'parquet';\n\nexport interface DownloadParams {\n  /** Exchange id, e.g. `binance`. */\n  exchangeId: string;\n  /** Base asset of the instrument, e.g. `BTC`. */\n  base: string;\n  /** Quote asset of the instrument, e.g. `USDT`. */\n  quote: string;\n  /** Hour selector in `YYYY-MM-DDTHH` (UTC). */\n  hour: string;\n  /** Defaults to `'lastra'`. */\n  format?: DownloadFormat;\n}\n\n/**\n * Download one hour of raw tickers as a {@link Blob}.\n *\n * The default wire format is Lastra (`application/vnd.lastra`); pass\n * `format: 'parquet'` for on-the-fly Parquet conversion.\n *\n * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure.\n */\nexport async function downloadTickers(params: DownloadParams): Promise<Blob> {\n  const { exchangeId, base, quote, hour, format } = params;\n  const { data, error, response } = await apiDownloadTickers({\n    path: { exchangeId, base, quote },\n    query: { hour, ...(format ? { format } : {}) },\n  });\n  if (error) {\n    throw new QTSDownloadError(\n      `tickers download failed: HTTP ${response.status} — ${describe(error)}`,\n      error,\n      response.status,\n    );\n  }\n  return data as Blob;\n}\n\n/**\n * Download one hour of klines as a {@link Blob}. See {@link downloadTickers}\n * for semantics.\n *\n * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure.\n */\nexport async function downloadKlines(params: DownloadParams): Promise<Blob> {\n  const { exchangeId, base, quote, hour, format } = params;\n  const { data, error, response } = await apiDownloadKlines({\n    path: { exchangeId, base, quote },\n    query: { hour, ...(format ? { format } : {}) },\n  });\n  if (error) {\n    throw new QTSDownloadError(\n      `klines download failed: HTTP ${response.status} — ${describe(error)}`,\n      error,\n      response.status,\n    );\n  }\n  return data as Blob;\n}\n\nfunction describe(error: unknown): string {\n  if (error && typeof error === 'object') {\n    const e = error as { code?: unknown; message?: unknown };\n    const code = typeof e.code === 'string' ? e.code : undefined;\n    const message = typeof e.message === 'string' ? e.message : undefined;\n    if (code && message) return `${code}: ${message}`;\n    if (message) return message;\n    if (code) return code;\n  }\n  return String(error);\n}\n","import {\n  authenticate as apiAuth,\n  client as apiClient,\n  type AuthTokenResponse,\n} from '@qtsurfer/api-client';\nimport { QTSAuthError } from '../errors';\nimport {\n  backtest as runBacktest,\n  type BacktestOptions,\n  type BacktestRequest,\n  type BacktestResult,\n} from '../workflows/backtest';\nimport {\n  downloadKlines,\n  downloadTickers,\n} from '../workflows/downloads';\nimport type { DownloadHourArgs } from '../client';\nimport { InMemoryTokenStore, type TokenStore } from './tokenStore';\n\nconst APIKEY_ENV_VAR = 'QTSURFER_APIKEY';\nconst DEFAULT_BASE_URL = 'https://api.qtsurfer.com/v1';\n\nexport interface AuthOptions {\n  /** Base URL of the QTSurfer API. Defaults to the public production endpoint. */\n  baseUrl?: string;\n  /** Custom token store. Defaults to {@link InMemoryTokenStore}. */\n  store?: TokenStore;\n  /** Inject a custom `fetch` (Node 20+, browser, or test mock). */\n  fetch?: typeof fetch;\n}\n\n/**\n * Authenticated SDK session.\n *\n * Returned by {@link authenticate}. Wraps the underlying api-client, owns a JWT\n * (in memory by default, or in the provided {@link TokenStore}), and\n * transparently re-exchanges the apikey for a fresh JWT on 401.\n *\n * Multi-session note: the session mutates the api-client singleton config\n * on every call. Concurrent sessions in the same process will race; today\n * the SDK targets the one-session-per-process pattern.\n */\nexport class AuthenticatedClient {\n  readonly baseUrl: string;\n  private readonly apikey: string;\n  private readonly store: TokenStore;\n  private readonly fetchImpl: typeof fetch | undefined;\n  private cached: AuthTokenResponse | null = null;\n  private refreshing: Promise<AuthTokenResponse> | null = null;\n\n  constructor(apikey: string, opts: AuthOptions = {}) {\n    this.apikey = apikey;\n    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;\n    this.store = opts.store ?? new InMemoryTokenStore();\n    this.fetchImpl = opts.fetch;\n  }\n\n  /** Currently cached token, if any. */\n  get token(): AuthTokenResponse | null {\n    return this.cached;\n  }\n\n  /** Force a fresh JWT exchange. Bypasses the cache. */\n  async refresh(): Promise<AuthTokenResponse> {\n    if (this.refreshing) return this.refreshing;\n    this.refreshing = (async () => {\n      const { data, error, response } = await apiAuth({\n        baseUrl: this.baseUrl,\n        headers: { 'X-API-Key': this.apikey },\n        ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),\n      });\n      if (error || !data) {\n        throw new QTSAuthError(\n          `authenticate() failed: HTTP ${response.status}`,\n          error,\n        );\n      }\n      this.cached = data;\n      await this.store.save(data);\n      return data;\n    })();\n    try {\n      return await this.refreshing;\n    } finally {\n      this.refreshing = null;\n    }\n  }\n\n  /**\n   * Load a previously-persisted token from the store. If none, mint one.\n   * Called automatically by every workflow method.\n   */\n  async ensureToken(): Promise<AuthTokenResponse> {\n    if (this.cached) return this.cached;\n    const stored = await this.store.load();\n    if (stored) {\n      this.cached = stored;\n      return stored;\n    }\n    return this.refresh();\n  }\n\n  /** Drop the cached token (in memory and in the store). */\n  async clear(): Promise<void> {\n    this.cached = null;\n    await this.store.clear();\n  }\n\n  /**\n   * Run a call with the Bearer header pre-set; if it returns 401, refresh\n   * once and retry. A second 401 surfaces to the caller.\n   */\n  private async withRefreshOn401<T>(call: () => Promise<T>): Promise<T> {\n    await this.applyConfig();\n    try {\n      return await call();\n    } catch (err) {\n      if (!isUnauthorized(err)) throw err;\n      this.cached = null;\n      await this.refresh();\n      await this.applyConfig();\n      return call();\n    }\n  }\n\n  private async applyConfig(): Promise<void> {\n    const token = await this.ensureToken();\n    apiClient.setConfig({\n      baseUrl: this.baseUrl,\n      headers: { Authorization: `Bearer ${token.access_token}` },\n      ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),\n    });\n  }\n\n  // ---- Workflow surface (mirrors QTSurfer) ----\n\n  /**\n   * Run a backtest end-to-end (compile → prepare → execute), sending the\n   * currently cached token (minting one first if none is cached). Unlike\n   * `tickers()`/`klines()`, a `401` here is not auto-retried: the underlying\n   * stage errors carry no HTTP status, so a token that expires mid-backtest\n   * surfaces as `QTSPreparationError`/`QTSExecutionError` rather than\n   * triggering a refresh.\n   */\n  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {\n    return this.withRefreshOn401(() => runBacktest(req, opts));\n  }\n\n  /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */\n  tickers(args: DownloadHourArgs): Promise<Blob> {\n    return this.withRefreshOn401(() => downloadTickers(args));\n  }\n\n  /** Download one hour of klines. Refreshes the token once on `401` before retrying. */\n  klines(args: DownloadHourArgs): Promise<Blob> {\n    return this.withRefreshOn401(() => downloadKlines(args));\n  }\n}\n\n/**\n * Exchange a long-lived API key for an authenticated session.\n *\n * If `apikey` is omitted, the SDK reads `QTSURFER_APIKEY` from the\n * environment. The returned {@link AuthenticatedClient} caches the JWT,\n * refreshes it on 401, and exposes the same workflow surface as\n * `QTSurfer` (`backtest`, `tickers`, `klines`).\n *\n * @throws {QTSAuthError} if no apikey is supplied or available in env.\n */\nexport async function authenticate(\n  apikey?: string,\n  opts: AuthOptions = {},\n): Promise<AuthenticatedClient> {\n  const resolved = apikey ?? readEnvApikey();\n  if (!resolved) {\n    throw new QTSAuthError(\n      `authenticate() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`,\n    );\n  }\n  const session = new AuthenticatedClient(resolved, opts);\n  await session.ensureToken();\n  return session;\n}\n\nfunction readEnvApikey(): string | undefined {\n  // `process` is undefined in browser bundlers; guard explicitly.\n  if (typeof process === 'undefined' || !process.env) return undefined;\n  const value = process.env[APIKEY_ENV_VAR];\n  return value && value.length > 0 ? value : undefined;\n}\n\nfunction isUnauthorized(err: unknown): boolean {\n  if (!err || typeof err !== 'object') return false;\n  // SDK-thrown errors (QTSDownloadError, etc.) carry the HTTP status on\n  // a top-level `status` field. Workflow errors that don't yet expose\n  // status default to non-401.\n  const maybeStatus = (err as { status?: unknown }).status;\n  if (typeof maybeStatus === 'number' && maybeStatus === 401) return true;\n  return false;\n}\n","import type { AuthTokenResponse } from '@qtsurfer/api-client';\n\n/**\n * Pluggable token persistence interface.\n *\n * The SDK ships an {@link InMemoryTokenStore} by default. Adopters can\n * implement this contract to back tokens by browser `localStorage`, an\n * on-disk file, a secret manager, etc.\n *\n * The SDK calls {@link load} once per session-startup to seed a cached\n * token (if any), {@link save} after every successful `authenticate()` / refresh,\n * and {@link clear} when the session is explicitly invalidated.\n */\nexport interface TokenStore {\n  /** Return the previously persisted token, or `null` if none. */\n  load(): AuthTokenResponse | null | Promise<AuthTokenResponse | null>;\n  /** Persist the token returned by `POST /v1/auth/token`. */\n  save(token: AuthTokenResponse): void | Promise<void>;\n  /** Drop any persisted token. */\n  clear(): void | Promise<void>;\n}\n\n/**\n * Default {@link TokenStore} — holds the token in a single in-memory slot.\n * Lost on process exit. Sufficient for short-lived scripts and tests.\n */\nexport class InMemoryTokenStore implements TokenStore {\n  private token: AuthTokenResponse | null = null;\n\n  load(): AuthTokenResponse | null {\n    return this.token;\n  }\n\n  save(token: AuthTokenResponse): void {\n    this.token = token;\n  }\n\n  clear(): void {\n    this.token = null;\n  }\n}\n"],"mappings":"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","names":["apiClient","apiClient"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qtsurfer/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Opinionated TypeScript SDK for QTSurfer: workflow orchestration, domain objects, normalized errors",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "tsup",
     "lint": "tsc --noEmit -p tsconfig.test.json",
+    "docs": "typedoc",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",
@@ -50,7 +51,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@qtsurfer/api-client": "^0.5.0",
+    "@qtsurfer/api-client": "^0.7.0",
     "cockatiel": "^3.2.1"
   },
   "devDependencies": {
@@ -59,6 +60,7 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
     "tsup": "^8.5.1",
+    "typedoc": "^0.28.20",
     "typescript": "^5.8.0",
     "vitest": "^4.1.4"
   },

package/src/auth/session.ts

@@ -134,14 +134,24 @@ export class AuthenticatedClient {
 
   // ---- Workflow surface (mirrors QTSurfer) ----
 
+  /**
+   * Run a backtest end-to-end (compile → prepare → execute), sending the
+   * currently cached token (minting one first if none is cached). Unlike
+   * `tickers()`/`klines()`, a `401` here is not auto-retried: the underlying
+   * stage errors carry no HTTP status, so a token that expires mid-backtest
+   * surfaces as `QTSPreparationError`/`QTSExecutionError` rather than
+   * triggering a refresh.
+   */
   backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {
     return this.withRefreshOn401(() => runBacktest(req, opts));
   }
 
+  /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */
   tickers(args: DownloadHourArgs): Promise<Blob> {
     return this.withRefreshOn401(() => downloadTickers(args));
   }
 
+  /** Download one hour of klines. Refreshes the token once on `401` before retrying. */
   klines(args: DownloadHourArgs): Promise<Blob> {
     return this.withRefreshOn401(() => downloadKlines(args));
   }

package/src/client.ts

@@ -11,15 +11,27 @@ import {
   type DownloadFormat,
 } from './workflows/downloads';
 
+/** Configuration for {@link QTSurfer}. */
 export interface QTSurferOptions {
+  /** Base URL of the QTSurfer API, e.g. `https://api.qtsurfer.com/v1`. */
   baseUrl: string;
+  /**
+   * Pre-obtained bearer token. When omitted, requests go out unauthenticated.
+   * Use the `authenticate()` helper instead of this constructor if you want
+   * the SDK to exchange an apikey for a JWT and refresh it on `401` for you.
+   */
   token?: string;
+  /** Inject a custom `fetch` (Node 20+, browser, or test mock). */
   fetch?: typeof fetch;
 }
 
+/** Selects one hour of tickers or klines for a single instrument. */
 export interface DownloadHourArgs {
+  /** Exchange id, e.g. `binance`. */
   exchangeId: string;
+  /** Base asset of the instrument, e.g. `BTC`. */
   base: string;
+  /** Quote asset of the instrument, e.g. `USDT`. */
   quote: string;
   /** Hour selector in `YYYY-MM-DDTHH` (UTC). */
   hour: string;
@@ -27,6 +39,14 @@ export interface DownloadHourArgs {
   format?: DownloadFormat;
 }
 
+/**
+ * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's
+ * workflow methods (`backtest`, `tickers`, `klines`). 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
+ * this constructor unless you already manage the JWT lifecycle yourself.
+ */
 export class QTSurfer {
   constructor(options: QTSurferOptions) {
     apiClient.setConfig({
@@ -38,6 +58,12 @@ export class QTSurfer {
     });
   }
 
+  /**
+   * Run a backtest end-to-end: compile the strategy, prepare the requested
+   * data range, execute it, and resolve with the result once execution
+   * completes. See the underlying `backtest` workflow for the
+   * stage-by-stage error and retry semantics.
+   */
   backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {
     return backtest(req, opts);
   }

package/src/errors.ts

@@ -1,3 +1,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.
+ */
 export class QTSError extends Error {
   /** HTTP status code, when the underlying transport surfaced one. */
   readonly status?: number;
@@ -8,6 +15,12 @@ export class QTSError extends Error {
   }
 }
 
+/**
+ * Thrown when strategy compilation fails. A `429` means the source was never
+ * judged — too many compilations were already in flight — and is safe to
+ * retry. Any other status (typically `400`) means the source itself does
+ * not compile, so retrying with the same input fails again.
+ */
 export class QTSStrategyCompileError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
@@ -15,6 +28,11 @@ export class QTSStrategyCompileError extends QTSError {
   }
 }
 
+/**
+ * Thrown when the data-preparation stage fails: submitting the prepare
+ * request, polling its status, or a backend-reported preparation failure
+ * (e.g. no data available for the requested range) all surface here.
+ */
 export class QTSPreparationError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
@@ -22,6 +40,11 @@ export class QTSPreparationError extends QTSError {
   }
 }
 
+/**
+ * Thrown when the execute stage fails: submitting the execute request,
+ * polling its result, or a backend-reported execution failure all surface
+ * here.
+ */
 export class QTSExecutionError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
@@ -29,6 +52,12 @@ export class QTSExecutionError extends QTSError {
   }
 }
 
+/**
+ * Thrown when a stage (prepare or execute) exceeds `timeoutMs`. The stage
+ * may still be running server-side — this only means the SDK stopped
+ * waiting locally — so it is fine to retry, optionally with a larger
+ * `timeoutMs`.
+ */
 export class QTSTimeoutError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
@@ -36,6 +65,12 @@ export class QTSTimeoutError extends QTSError {
   }
 }
 
+/**
+ * Thrown when a stage is aborted — either because the caller's
+ * `AbortSignal` fired, or because the backend itself reported the
+ * prepare/execute job as aborted. Either way this reflects a deliberate
+ * stop, not a failure, and is not something to retry automatically.
+ */
 export class QTSCanceledError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
@@ -43,6 +78,12 @@ export class QTSCanceledError extends QTSError {
   }
 }
 
+/**
+ * Thrown by the tickers/klines download functions on any non-2xx response or
+ * transport failure. Carries the HTTP `status` when one was received: a
+ * `4xx` means the request itself is wrong (bad hour or instrument), while a
+ * `5xx` or a missing status (transport failure) is generally safe to retry.
+ */
 export class QTSDownloadError extends QTSError {
   constructor(message: string, cause?: unknown, status?: number) {
     super(message, cause, status);

package/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * Public surface of `@qtsurfer/sdk`. Everything a consumer needs — the
+ * `QTSurfer` client, the `authenticate()` session helper, workflow types,
+ * and the `QTSError` hierarchy — is re-exported from here; see each
+ * symbol's own doc comment for behavior and retry semantics.
+ */
 export { QTSurfer, type QTSurferOptions, type DownloadHourArgs } from './client';
 export {
   QTSError,

package/src/workflows/backtest.ts

@@ -3,7 +3,6 @@ import {
   executeBacktest,
   getBacktestResult,
   getPrepareStatus,
-  getStrategy,
   compileStrategy as apiCompileStrategy,
   prepareBacktest,
   type DataSourceType,
@@ -43,8 +42,16 @@ export interface BacktestRequest {
   storeSignals?: boolean;
 }
 
+/**
+ * Resolved value of the backtest workflow (see {@link QTSurfer.backtest}).
+ * Alias for api-client's `ResultMap` — always includes core fields
+ * (`hostName`, `iops`, `instrument`); yield metrics (`pnlTotal`,
+ * `totalTrades`, `equityCurve`, etc.) are only present once the strategy
+ * has emitted at least one trade.
+ */
 export type BacktestResult = ResultMap;
 
+/** The three sequential stages {@link QTSurfer.backtest} moves through, in order. */
 export type BacktestStage = 'compiling' | 'preparing' | 'executing';
 
 export interface BacktestProgress {
@@ -80,6 +87,12 @@ 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';
 
@@ -90,7 +103,7 @@ function normalizeStatus(raw: unknown): NormalizedStatus {
   if (value === 'aborted' || value === 'cancelled' || value === 'canceled') {
     return 'aborted';
   }
-  // new / started / queued / running / anything else → still running
+  // new / started / queued / running / absent (202) / anything else → still running
   return 'in-progress';
 }
 
@@ -100,9 +113,9 @@ export async function backtest(
 ): Promise<BacktestResult> {
   const policy = buildStagePolicy(opts);
 
-  // 1. Compile strategy (async mode)
+  // 1. Compile strategy (single synchronous request)
   opts.onProgress?.({ stage: 'compiling' });
-  const strategyId = await compileStrategy(req.strategy, policy, opts);
+  const strategyId = await compileStrategy(req.strategy, opts);
 
   // 2. Prepare data
   opts.onProgress?.({ stage: 'preparing' });
@@ -133,50 +146,33 @@ function buildStagePolicy(opts: BacktestOptions): IPolicy<ICancellationContext,
     : retryPolicy;
 }
 
-async function compileStrategy(
-  source: string,
-  policy: IPolicy<ICancellationContext, never>,
-  opts: BacktestOptions,
-): Promise<string> {
-  const { data, error } = await apiCompileStrategy({
+/**
+ * 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,
-    headers: { 'X-Compile-Async': true },
     ...(opts.signal ? { signal: opts.signal } : {}),
   });
-  if (error) throw new QTSStrategyCompileError('Strategy submission failed', error);
-  if (!data) throw new QTSStrategyCompileError('Empty response from strategy endpoint');
-
-  // Sync mode returns { strategyId }; async mode returns { jobId }.
-  if ('strategyId' in data && data.strategyId) {
-    return data.strategyId;
-  }
-  if (!('jobId' in data) || !data.jobId) {
-    throw new QTSStrategyCompileError('Missing jobId/strategyId in compile response');
-  }
 
-  const compileJobId = data.jobId;
-  const status = await runStage(
-    policy,
-    opts,
-    async ({ signal }) => {
-      const res = await getStrategy({ path: { strategyId: compileJobId }, signal });
-      if (res.error) throw new QTSStrategyCompileError('Compile status request failed', res.error);
-      if (!res.data) throw new QTSStrategyCompileError('Empty compile status response');
-      return res.data;
-    },
-  );
-
-  const norm = normalizeStatus(status.status);
-  if (norm === 'failed') {
-    throw new QTSStrategyCompileError(status.statusDetail ?? 'Strategy compilation failed');
-  }
-  if (norm === 'aborted') {
-    throw new QTSCanceledError('Strategy compilation aborted');
+  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 (!status.strategyId) {
-    throw new QTSStrategyCompileError('Compile completed without a strategyId');
+  if (!data?.strategyId) {
+    throw new QTSStrategyCompileError('Compile response missing strategyId');
   }
-  return status.strategyId;
+  return data.strategyId;
 }
 
 async function prepareData(
@@ -257,6 +253,9 @@ async function executeStrategy(
         });
         if (res.error) throw new QTSExecutionError('Execution result request failed', res.error);
         if (!res.data) throw new QTSExecutionError('Empty execution result response');
+        // A 202 carries an empty body: no `state`, so the spread yields an undefined status and
+        // the retry predicate keeps polling. That is the intended handling, not a coincidence —
+        // 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) => {

package/src/workflows/downloads.ts

@@ -8,12 +8,15 @@ import { QTSDownloadError } from '../errors';
 export type DownloadFormat = 'lastra' | 'parquet';
 
 export interface DownloadParams {
+  /** Exchange id, e.g. `binance`. */
   exchangeId: string;
+  /** Base asset of the instrument, e.g. `BTC`. */
   base: string;
+  /** Quote asset of the instrument, e.g. `USDT`. */
   quote: string;
   /** Hour selector in `YYYY-MM-DDTHH` (UTC). */
   hour: string;
-  /** Defaults to {@code 'lastra'}. */
+  /** Defaults to `'lastra'`. */
   format?: DownloadFormat;
 }