@qtsurfer/sdk 0.6.0 → 0.6.1

package/README.md

@@ -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.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\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 *\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 (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        // 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","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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qtsurfer/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Opinionated TypeScript SDK for QTSurfer: workflow orchestration, domain objects, normalized errors",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@qtsurfer/api-client": "^0.5.0",
+    "@qtsurfer/api-client": "^0.6.0",
     "cockatiel": "^3.2.1"
   },
   "devDependencies": {

package/src/workflows/backtest.ts

@@ -80,6 +80,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 +96,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';
 }
 
@@ -257,6 +263,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) => {