@qtsurfer/sdk 0.2.0 → 0.4.0

package/README.md

@@ -20,38 +20,68 @@ pnpm add @qtsurfer/sdk
 
 ## Quick start
 
+One call: API key in, ready-to-use session out. JWT refresh on 401 is handled
+for you.
+
 ```ts
-import { QTSurfer } from '@qtsurfer/sdk';
+import { auth } from '@qtsurfer/sdk';
 import { readFileSync } from 'node:fs';
 
-const qts = new QTSurfer({
-  baseUrl: 'https://api.qtsurfer.com/v1',
-  token: process.env.QTSURFER_TOKEN,
-});
-
-const controller = new AbortController();
+// Reads QTSURFER_APIKEY from env when no argument is passed.
+const qts = await auth();
+// Or: const qts = await auth('ak_...');
 
-const result = await qts.backtest(
-  {
-    strategy: readFileSync('./MyStrategy.java', 'utf8'),
-    exchangeId: 'binance',
-    instrument: 'BTC/USDT',
-    from: '2024-01-01',
-    to: '2024-12-31',
-    storeSignals: true,
-  },
-  {
-    signal: controller.signal,
-    onProgress: (p) => console.log(`[${p.stage}] ${p.percent?.toFixed(1) ?? '-'}%`),
-    pollIntervalMs: 500,
-    maxPollIntervalMs: 5000,
-    timeoutMs: 10 * 60 * 1000,
-  },
-);
+const result = await qts.backtest({
+  strategy: readFileSync('./MyStrategy.java', 'utf8'),
+  exchangeId: 'binance',
+  instrument: 'BTC/USDT',
+  from: '2024-01-01',
+  to: '2024-12-31',
+  storeSignals: true,
+});
 
 console.log('PnL:', result.pnlTotal);
 console.log('Trades:', result.totalTrades);
-console.log('Signals:', result.signalsUrl);
+```
+
+### Environment
+
+| Variable           | Purpose                                            |
+| ------------------ | -------------------------------------------------- |
+| `QTSURFER_APIKEY`  | API key consumed by `auth()` when no arg is passed |
+
+### Pluggable token storage
+
+Tokens are kept in memory by default. Implement `TokenStore` to swap in
+browser storage, a file, or a secret manager:
+
+```ts
+import { auth, type TokenStore, type AuthTokenResponse } from '@qtsurfer/sdk';
+
+const browserStore: TokenStore = {
+  load: () => JSON.parse(localStorage.getItem('qts.jwt') ?? 'null'),
+  save: (t) => localStorage.setItem('qts.jwt', JSON.stringify(t)),
+  clear: () => localStorage.removeItem('qts.jwt'),
+};
+
+const qts = await auth(undefined, { store: browserStore });
+```
+
+`auth()` also accepts `{ baseUrl, fetch }` for staging, custom HTTP
+transports, or a Node-`fetch` polyfill in legacy runtimes.
+
+### Lower-level: hand-managed JWT
+
+If you already hold a JWT and want to manage refresh yourself, the
+`QTSurfer` constructor still accepts a `token`:
+
+```ts
+import { QTSurfer } from '@qtsurfer/sdk';
+
+const qts = new QTSurfer({
+  baseUrl: 'https://api.qtsurfer.com/v1',
+  token: process.env.QTSURFER_TOKEN,
+});
 ```
 
 ## What `backtest()` does

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ResultMap } from '@qtsurfer/api-client';
+import { ResultMap, AuthTokenResponse } from '@qtsurfer/api-client';
 
 interface BacktestRequest {
     /** Strategy source code (Java) */
@@ -65,7 +65,9 @@ declare class QTSurfer {
 
 declare class QTSError extends Error {
     readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    /** HTTP status code, when the underlying transport surfaced one. */
+    readonly status?: number;
+    constructor(message: string, cause?: unknown | undefined, status?: number);
 }
 declare class QTSStrategyCompileError extends QTSError {
     constructor(message: string, cause?: unknown);
@@ -83,7 +85,104 @@ declare class QTSCanceledError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
 declare class QTSDownloadError extends QTSError {
+    constructor(message: string, cause?: unknown, status?: number);
+}
+/**
+ * Thrown by the `auth()` helper when the apikey is missing or the JWT
+ * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).
+ */
+declare class QTSAuthError extends QTSError {
     constructor(message: string, cause?: unknown);
 }
 
-export { type BacktestOptions, type BacktestProgress, type BacktestRequest, type BacktestResult, type BacktestStage, type DownloadFormat, type DownloadHourArgs, QTSCanceledError, QTSDownloadError, QTSError, QTSExecutionError, QTSPreparationError, QTSStrategyCompileError, QTSTimeoutError, QTSurfer, type QTSurferOptions };
+/**
+ * Pluggable token persistence interface.
+ *
+ * The SDK ships an {@link InMemoryTokenStore} by default. Adopters can
+ * implement this contract to back tokens by browser `localStorage`, an
+ * on-disk file, a secret manager, etc.
+ *
+ * The SDK calls {@link load} once per session-startup to seed a cached
+ * token (if any), {@link save} after every successful `auth()` / refresh,
+ * and {@link clear} when the session is explicitly invalidated.
+ */
+interface TokenStore {
+    /** Return the previously persisted token, or `null` if none. */
+    load(): AuthTokenResponse | null | Promise<AuthTokenResponse | null>;
+    /** Persist the token returned by `POST /v1/auth/token`. */
+    save(token: AuthTokenResponse): void | Promise<void>;
+    /** Drop any persisted token. */
+    clear(): void | Promise<void>;
+}
+/**
+ * Default {@link TokenStore} — holds the token in a single in-memory slot.
+ * Lost on process exit. Sufficient for short-lived scripts and tests.
+ */
+declare class InMemoryTokenStore implements TokenStore {
+    private token;
+    load(): AuthTokenResponse | null;
+    save(token: AuthTokenResponse): void;
+    clear(): void;
+}
+
+interface AuthOptions {
+    /** Base URL of the QTSurfer API. Defaults to the public production endpoint. */
+    baseUrl?: string;
+    /** Custom token store. Defaults to {@link InMemoryTokenStore}. */
+    store?: TokenStore;
+    /** Inject a custom `fetch` (Node 20+, browser, or test mock). */
+    fetch?: typeof fetch;
+}
+/**
+ * Authenticated SDK session.
+ *
+ * Returned by {@link auth}. Wraps the underlying api-client, owns a JWT
+ * (in memory by default, or in the provided {@link TokenStore}), and
+ * transparently re-exchanges the apikey for a fresh JWT on 401.
+ *
+ * Multi-session note: the session mutates the api-client singleton config
+ * on every call. Concurrent sessions in the same process will race; today
+ * the SDK targets the one-session-per-process pattern.
+ */
+declare class AuthenticatedClient {
+    readonly baseUrl: string;
+    private readonly apikey;
+    private readonly store;
+    private readonly fetchImpl;
+    private cached;
+    private refreshing;
+    constructor(apikey: string, opts?: AuthOptions);
+    /** Currently cached token, if any. */
+    get token(): AuthTokenResponse | null;
+    /** Force a fresh JWT exchange. Bypasses the cache. */
+    refresh(): Promise<AuthTokenResponse>;
+    /**
+     * Load a previously-persisted token from the store. If none, mint one.
+     * Called automatically by every workflow method.
+     */
+    ensureToken(): Promise<AuthTokenResponse>;
+    /** Drop the cached token (in memory and in the store). */
+    clear(): Promise<void>;
+    /**
+     * Run a call with the Bearer header pre-set; if it returns 401, refresh
+     * once and retry. A second 401 surfaces to the caller.
+     */
+    private withRefreshOn401;
+    private applyConfig;
+    backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+    tickers(args: DownloadHourArgs): Promise<Blob>;
+    klines(args: DownloadHourArgs): Promise<Blob>;
+}
+/**
+ * Exchange a long-lived API key for an authenticated session.
+ *
+ * If `apikey` is omitted, the SDK reads `QTSURFER_APIKEY` from the
+ * environment. The returned {@link AuthenticatedClient} caches the JWT,
+ * refreshes it on 401, and exposes the same workflow surface as
+ * `QTSurfer` (`backtest`, `tickers`, `klines`).
+ *
+ * @throws {QTSAuthError} if no apikey is supplied or available in env.
+ */
+declare function auth(apikey?: string, opts?: AuthOptions): Promise<AuthenticatedClient>;
+
+export { type AuthOptions, AuthenticatedClient, type BacktestOptions, type BacktestProgress, type BacktestRequest, type BacktestResult, type BacktestStage, type DownloadFormat, type DownloadHourArgs, InMemoryTokenStore, QTSAuthError, QTSCanceledError, QTSDownloadError, QTSError, QTSExecutionError, QTSPreparationError, QTSStrategyCompileError, QTSTimeoutError, QTSurfer, type QTSurferOptions, type TokenStore, auth };

package/dist/index.js

@@ -23,12 +23,15 @@ import {
 
 // src/errors.ts
 var QTSError = class extends Error {
-  constructor(message, cause) {
+  constructor(message, cause, status) {
     super(message);
     this.cause = cause;
     this.name = "QTSError";
+    if (status !== void 0) this.status = status;
   }
   cause;
+  /** HTTP status code, when the underlying transport surfaced one. */
+  status;
 };
 var QTSStrategyCompileError = class extends QTSError {
   constructor(message, cause) {
@@ -61,9 +64,15 @@ var QTSCanceledError = class extends QTSError {
   }
 };
 var QTSDownloadError = class extends QTSError {
+  constructor(message, cause, status) {
+    super(message, cause, status);
+    this.name = "QTSDownloadError";
+  }
+};
+var QTSAuthError = class extends QTSError {
   constructor(message, cause) {
     super(message, cause);
-    this.name = "QTSDownloadError";
+    this.name = "QTSAuthError";
   }
 };
 
@@ -259,7 +268,8 @@ async function downloadTickers(params) {
   if (error) {
     throw new QTSDownloadError(
       `tickers download failed: HTTP ${response.status} \u2014 ${describe(error)}`,
-      error
+      error,
+      response.status
     );
   }
   return data;
@@ -273,7 +283,8 @@ async function downloadKlines(params) {
   if (error) {
     throw new QTSDownloadError(
       `klines download failed: HTTP ${response.status} \u2014 ${describe(error)}`,
-      error
+      error,
+      response.status
     );
   }
   return data;
@@ -318,7 +329,151 @@ var QTSurfer = class {
   //   instruments: { list, get } with TTL cache
   //   jobs: { cancel, stream, result }
 };
+
+// src/auth/session.ts
+import {
+  auth as apiAuth,
+  client as apiClient2
+} from "@qtsurfer/api-client";
+
+// src/auth/tokenStore.ts
+var InMemoryTokenStore = class {
+  token = null;
+  load() {
+    return this.token;
+  }
+  save(token) {
+    this.token = token;
+  }
+  clear() {
+    this.token = null;
+  }
+};
+
+// src/auth/session.ts
+var APIKEY_ENV_VAR = "QTSURFER_APIKEY";
+var DEFAULT_BASE_URL = "https://api.qtsurfer.com/v1";
+var AuthenticatedClient = class {
+  baseUrl;
+  apikey;
+  store;
+  fetchImpl;
+  cached = null;
+  refreshing = null;
+  constructor(apikey, opts = {}) {
+    this.apikey = apikey;
+    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    this.store = opts.store ?? new InMemoryTokenStore();
+    this.fetchImpl = opts.fetch;
+  }
+  /** Currently cached token, if any. */
+  get token() {
+    return this.cached;
+  }
+  /** Force a fresh JWT exchange. Bypasses the cache. */
+  async refresh() {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = (async () => {
+      const { data, error, response } = await apiAuth({
+        baseUrl: this.baseUrl,
+        headers: { "X-API-Key": this.apikey },
+        ...this.fetchImpl ? { fetch: this.fetchImpl } : {}
+      });
+      if (error || !data) {
+        throw new QTSAuthError(
+          `auth() failed: HTTP ${response.status}`,
+          error
+        );
+      }
+      this.cached = data;
+      await this.store.save(data);
+      return data;
+    })();
+    try {
+      return await this.refreshing;
+    } finally {
+      this.refreshing = null;
+    }
+  }
+  /**
+   * Load a previously-persisted token from the store. If none, mint one.
+   * Called automatically by every workflow method.
+   */
+  async ensureToken() {
+    if (this.cached) return this.cached;
+    const stored = await this.store.load();
+    if (stored) {
+      this.cached = stored;
+      return stored;
+    }
+    return this.refresh();
+  }
+  /** Drop the cached token (in memory and in the store). */
+  async clear() {
+    this.cached = null;
+    await this.store.clear();
+  }
+  /**
+   * Run a call with the Bearer header pre-set; if it returns 401, refresh
+   * once and retry. A second 401 surfaces to the caller.
+   */
+  async withRefreshOn401(call) {
+    await this.applyConfig();
+    try {
+      return await call();
+    } catch (err) {
+      if (!isUnauthorized(err)) throw err;
+      this.cached = null;
+      await this.refresh();
+      await this.applyConfig();
+      return call();
+    }
+  }
+  async applyConfig() {
+    const token = await this.ensureToken();
+    apiClient2.setConfig({
+      baseUrl: this.baseUrl,
+      headers: { Authorization: `Bearer ${token.access_token}` },
+      ...this.fetchImpl ? { fetch: this.fetchImpl } : {}
+    });
+  }
+  // ---- Workflow surface (mirrors QTSurfer) ----
+  backtest(req, opts) {
+    return this.withRefreshOn401(() => backtest(req, opts));
+  }
+  tickers(args) {
+    return this.withRefreshOn401(() => downloadTickers(args));
+  }
+  klines(args) {
+    return this.withRefreshOn401(() => downloadKlines(args));
+  }
+};
+async function auth(apikey, opts = {}) {
+  const resolved = apikey ?? readEnvApikey();
+  if (!resolved) {
+    throw new QTSAuthError(
+      `auth() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`
+    );
+  }
+  const session = new AuthenticatedClient(resolved, opts);
+  await session.ensureToken();
+  return session;
+}
+function readEnvApikey() {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  const value = process.env[APIKEY_ENV_VAR];
+  return value && value.length > 0 ? value : void 0;
+}
+function isUnauthorized(err) {
+  if (!err || typeof err !== "object") return false;
+  const maybeStatus = err.status;
+  if (typeof maybeStatus === "number" && maybeStatus === 401) return true;
+  return false;
+}
 export {
+  AuthenticatedClient,
+  InMemoryTokenStore,
+  QTSAuthError,
   QTSCanceledError,
   QTSDownloadError,
   QTSError,
@@ -326,6 +481,7 @@ export {
   QTSPreparationError,
   QTSStrategyCompileError,
   QTSTimeoutError,
-  QTSurfer
+  QTSurfer,
+  auth
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts","../src/workflows/backtest.ts","../src/errors.ts","../src/workflows/downloads.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  cancelExecution,\n  executeBacktesting,\n  getExecutionResult,\n  getPreparationStatus,\n  getStrategyStatus,\n  postStrategy,\n  prepareBacktesting,\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\nexport interface BacktestOptions {\n  /** Abort the workflow. Cancels the current poll and calls `cancelExecution` 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' | 'Partial';\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 postStrategy({\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 getStrategyStatus({ 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 prepareBacktesting({\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 getPreparationStatus({\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  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 executeBacktesting({\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 getExecutionResult({\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 cancelExecution({\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  constructor(message: string, readonly cause?: unknown) {\n    super(message);\n    this.name = 'QTSError';\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) {\n    super(message, cause);\n    this.name = 'QTSDownloadError';\n  }\n}\n","import {\n  getExchangeKlinesHour,\n  getExchangeTickersHour,\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 getExchangeTickersHour({\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    );\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 getExchangeKlinesHour({\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    );\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"],"mappings":"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","names":[]}
+{"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  cancelExecution,\n  executeBacktesting,\n  getExecutionResult,\n  getPreparationStatus,\n  getStrategyStatus,\n  postStrategy,\n  prepareBacktesting,\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\nexport interface BacktestOptions {\n  /** Abort the workflow. Cancels the current poll and calls `cancelExecution` 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' | 'Partial';\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 postStrategy({\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 getStrategyStatus({ 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 prepareBacktesting({\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 getPreparationStatus({\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  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 executeBacktesting({\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 getExecutionResult({\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 cancelExecution({\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 `auth()` 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  getExchangeKlinesHour,\n  getExchangeTickersHour,\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 getExchangeTickersHour({\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 getExchangeKlinesHour({\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  auth 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 auth}. 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          `auth() 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 auth(\n  apikey?: string,\n  opts: AuthOptions = {},\n): Promise<AuthenticatedClient> {\n  const resolved = apikey ?? readEnvApikey();\n  if (!resolved) {\n    throw new QTSAuthError(\n      `auth() 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 `auth()` / 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.2.0",
+  "version": "0.4.0",
   "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.1.2",
+    "@qtsurfer/api-client": "^0.3.0",
     "cockatiel": "^3.2.1"
   },
   "devDependencies": {

package/src/auth/session.ts

@@ -0,0 +1,190 @@
+import {
+  auth as apiAuth,
+  client as apiClient,
+  type AuthTokenResponse,
+} from '@qtsurfer/api-client';
+import { QTSAuthError } from '../errors';
+import {
+  backtest as runBacktest,
+  type BacktestOptions,
+  type BacktestRequest,
+  type BacktestResult,
+} from '../workflows/backtest';
+import {
+  downloadKlines,
+  downloadTickers,
+} from '../workflows/downloads';
+import type { DownloadHourArgs } from '../client';
+import { InMemoryTokenStore, type TokenStore } from './tokenStore';
+
+const APIKEY_ENV_VAR = 'QTSURFER_APIKEY';
+const DEFAULT_BASE_URL = 'https://api.qtsurfer.com/v1';
+
+export interface AuthOptions {
+  /** Base URL of the QTSurfer API. Defaults to the public production endpoint. */
+  baseUrl?: string;
+  /** Custom token store. Defaults to {@link InMemoryTokenStore}. */
+  store?: TokenStore;
+  /** Inject a custom `fetch` (Node 20+, browser, or test mock). */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Authenticated SDK session.
+ *
+ * Returned by {@link auth}. Wraps the underlying api-client, owns a JWT
+ * (in memory by default, or in the provided {@link TokenStore}), and
+ * transparently re-exchanges the apikey for a fresh JWT on 401.
+ *
+ * Multi-session note: the session mutates the api-client singleton config
+ * on every call. Concurrent sessions in the same process will race; today
+ * the SDK targets the one-session-per-process pattern.
+ */
+export class AuthenticatedClient {
+  readonly baseUrl: string;
+  private readonly apikey: string;
+  private readonly store: TokenStore;
+  private readonly fetchImpl: typeof fetch | undefined;
+  private cached: AuthTokenResponse | null = null;
+  private refreshing: Promise<AuthTokenResponse> | null = null;
+
+  constructor(apikey: string, opts: AuthOptions = {}) {
+    this.apikey = apikey;
+    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    this.store = opts.store ?? new InMemoryTokenStore();
+    this.fetchImpl = opts.fetch;
+  }
+
+  /** Currently cached token, if any. */
+  get token(): AuthTokenResponse | null {
+    return this.cached;
+  }
+
+  /** Force a fresh JWT exchange. Bypasses the cache. */
+  async refresh(): Promise<AuthTokenResponse> {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = (async () => {
+      const { data, error, response } = await apiAuth({
+        baseUrl: this.baseUrl,
+        headers: { 'X-API-Key': this.apikey },
+        ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),
+      });
+      if (error || !data) {
+        throw new QTSAuthError(
+          `auth() failed: HTTP ${response.status}`,
+          error,
+        );
+      }
+      this.cached = data;
+      await this.store.save(data);
+      return data;
+    })();
+    try {
+      return await this.refreshing;
+    } finally {
+      this.refreshing = null;
+    }
+  }
+
+  /**
+   * Load a previously-persisted token from the store. If none, mint one.
+   * Called automatically by every workflow method.
+   */
+  async ensureToken(): Promise<AuthTokenResponse> {
+    if (this.cached) return this.cached;
+    const stored = await this.store.load();
+    if (stored) {
+      this.cached = stored;
+      return stored;
+    }
+    return this.refresh();
+  }
+
+  /** Drop the cached token (in memory and in the store). */
+  async clear(): Promise<void> {
+    this.cached = null;
+    await this.store.clear();
+  }
+
+  /**
+   * Run a call with the Bearer header pre-set; if it returns 401, refresh
+   * once and retry. A second 401 surfaces to the caller.
+   */
+  private async withRefreshOn401<T>(call: () => Promise<T>): Promise<T> {
+    await this.applyConfig();
+    try {
+      return await call();
+    } catch (err) {
+      if (!isUnauthorized(err)) throw err;
+      this.cached = null;
+      await this.refresh();
+      await this.applyConfig();
+      return call();
+    }
+  }
+
+  private async applyConfig(): Promise<void> {
+    const token = await this.ensureToken();
+    apiClient.setConfig({
+      baseUrl: this.baseUrl,
+      headers: { Authorization: `Bearer ${token.access_token}` },
+      ...(this.fetchImpl ? { fetch: this.fetchImpl } : {}),
+    });
+  }
+
+  // ---- Workflow surface (mirrors QTSurfer) ----
+
+  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {
+    return this.withRefreshOn401(() => runBacktest(req, opts));
+  }
+
+  tickers(args: DownloadHourArgs): Promise<Blob> {
+    return this.withRefreshOn401(() => downloadTickers(args));
+  }
+
+  klines(args: DownloadHourArgs): Promise<Blob> {
+    return this.withRefreshOn401(() => downloadKlines(args));
+  }
+}
+
+/**
+ * Exchange a long-lived API key for an authenticated session.
+ *
+ * If `apikey` is omitted, the SDK reads `QTSURFER_APIKEY` from the
+ * environment. The returned {@link AuthenticatedClient} caches the JWT,
+ * refreshes it on 401, and exposes the same workflow surface as
+ * `QTSurfer` (`backtest`, `tickers`, `klines`).
+ *
+ * @throws {QTSAuthError} if no apikey is supplied or available in env.
+ */
+export async function auth(
+  apikey?: string,
+  opts: AuthOptions = {},
+): Promise<AuthenticatedClient> {
+  const resolved = apikey ?? readEnvApikey();
+  if (!resolved) {
+    throw new QTSAuthError(
+      `auth() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`,
+    );
+  }
+  const session = new AuthenticatedClient(resolved, opts);
+  await session.ensureToken();
+  return session;
+}
+
+function readEnvApikey(): string | undefined {
+  // `process` is undefined in browser bundlers; guard explicitly.
+  if (typeof process === 'undefined' || !process.env) return undefined;
+  const value = process.env[APIKEY_ENV_VAR];
+  return value && value.length > 0 ? value : undefined;
+}
+
+function isUnauthorized(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  // SDK-thrown errors (QTSDownloadError, etc.) carry the HTTP status on
+  // a top-level `status` field. Workflow errors that don't yet expose
+  // status default to non-401.
+  const maybeStatus = (err as { status?: unknown }).status;
+  if (typeof maybeStatus === 'number' && maybeStatus === 401) return true;
+  return false;
+}

package/src/auth/tokenStore.ts

@@ -0,0 +1,41 @@
+import type { AuthTokenResponse } from '@qtsurfer/api-client';
+
+/**
+ * Pluggable token persistence interface.
+ *
+ * The SDK ships an {@link InMemoryTokenStore} by default. Adopters can
+ * implement this contract to back tokens by browser `localStorage`, an
+ * on-disk file, a secret manager, etc.
+ *
+ * The SDK calls {@link load} once per session-startup to seed a cached
+ * token (if any), {@link save} after every successful `auth()` / refresh,
+ * and {@link clear} when the session is explicitly invalidated.
+ */
+export interface TokenStore {
+  /** Return the previously persisted token, or `null` if none. */
+  load(): AuthTokenResponse | null | Promise<AuthTokenResponse | null>;
+  /** Persist the token returned by `POST /v1/auth/token`. */
+  save(token: AuthTokenResponse): void | Promise<void>;
+  /** Drop any persisted token. */
+  clear(): void | Promise<void>;
+}
+
+/**
+ * Default {@link TokenStore} — holds the token in a single in-memory slot.
+ * Lost on process exit. Sufficient for short-lived scripts and tests.
+ */
+export class InMemoryTokenStore implements TokenStore {
+  private token: AuthTokenResponse | null = null;
+
+  load(): AuthTokenResponse | null {
+    return this.token;
+  }
+
+  save(token: AuthTokenResponse): void {
+    this.token = token;
+  }
+
+  clear(): void {
+    this.token = null;
+  }
+}

package/src/errors.ts

@@ -1,7 +1,10 @@
 export class QTSError extends Error {
-  constructor(message: string, readonly cause?: unknown) {
+  /** HTTP status code, when the underlying transport surfaced one. */
+  readonly status?: number;
+  constructor(message: string, readonly cause?: unknown, status?: number) {
     super(message);
     this.name = 'QTSError';
+    if (status !== undefined) this.status = status;
   }
 }
 
@@ -41,8 +44,19 @@ export class QTSCanceledError extends QTSError {
 }
 
 export class QTSDownloadError extends QTSError {
+  constructor(message: string, cause?: unknown, status?: number) {
+    super(message, cause, status);
+    this.name = 'QTSDownloadError';
+  }
+}
+
+/**
+ * Thrown by the `auth()` helper when the apikey is missing or the JWT
+ * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).
+ */
+export class QTSAuthError extends QTSError {
   constructor(message: string, cause?: unknown) {
     super(message, cause);
-    this.name = 'QTSDownloadError';
+    this.name = 'QTSAuthError';
   }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   QTSTimeoutError,
   QTSCanceledError,
   QTSDownloadError,
+  QTSAuthError,
 } from './errors';
 export type {
   BacktestRequest,
@@ -16,3 +17,12 @@ export type {
   BacktestOptions,
 } from './workflows/backtest';
 export type { DownloadFormat } from './workflows/downloads';
+export {
+  auth,
+  AuthenticatedClient,
+  type AuthOptions,
+} from './auth/session';
+export {
+  InMemoryTokenStore,
+  type TokenStore,
+} from './auth/tokenStore';

package/src/workflows/downloads.ts

@@ -35,6 +35,7 @@ export async function downloadTickers(params: DownloadParams): Promise<Blob> {
     throw new QTSDownloadError(
       `tickers download failed: HTTP ${response.status} — ${describe(error)}`,
       error,
+      response.status,
     );
   }
   return data as Blob;
@@ -56,6 +57,7 @@ export async function downloadKlines(params: DownloadParams): Promise<Blob> {
     throw new QTSDownloadError(
       `klines download failed: HTTP ${response.status} — ${describe(error)}`,
       error,
+      response.status,
     );
   }
   return data as Blob;