npm - @qtsurfer/sdk - Versions diffs - 0.4.0 → 0.6.0 - Mend

@qtsurfer/sdk 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +10 -10
package/dist/index.d.ts +12 -6
package/dist/index.js +24 -23
package/dist/index.js.map +1 -1
package/package.json +2 -2
package/src/auth/session.ts +5 -5
package/src/auth/tokenStore.ts +1 -1
package/src/errors.ts +1 -1
package/src/index.ts +1 -1
package/src/workflows/backtest.ts +25 -16
package/src/workflows/downloads.ts +4 -4

package/README.md CHANGED Viewed

@@ -24,12 +24,12 @@ One call: API key in, ready-to-use session out. JWT refresh on 401 is handled
 for you.
 ```ts
-import { auth } from '@qtsurfer/sdk';
+import { authenticate } from '@qtsurfer/sdk';
 import { readFileSync } from 'node:fs';
 // Reads QTSURFER_APIKEY from env when no argument is passed.
-const qts = await auth();
-// Or: const qts = await auth('ak_...');
+const qts = await authenticate();
+// Or: const qts = await authenticate('ak_...');
 const result = await qts.backtest({
   strategy: readFileSync('./MyStrategy.java', 'utf8'),
@@ -46,9 +46,9 @@ console.log('Trades:', result.totalTrades);
 ### Environment
-| Variable           | Purpose                                            |
-| ------------------ | -------------------------------------------------- |
-| `QTSURFER_APIKEY`  | API key consumed by `auth()` when no arg is passed |
+| Variable           | Purpose                                                     |
+| ------------------ | ------------------------------------------------------------ |
+| `QTSURFER_APIKEY`  | API key consumed by `authenticate()` when no arg is passed   |
 ### Pluggable token storage
@@ -56,7 +56,7 @@ 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';
+import { authenticate, type TokenStore, type AuthTokenResponse } from '@qtsurfer/sdk';
 const browserStore: TokenStore = {
   load: () => JSON.parse(localStorage.getItem('qts.jwt') ?? 'null'),
@@ -64,10 +64,10 @@ const browserStore: TokenStore = {
   clear: () => localStorage.removeItem('qts.jwt'),
 };
-const qts = await auth(undefined, { store: browserStore });
+const qts = await authenticate(undefined, { store: browserStore });
 ```
-`auth()` also accepts `{ baseUrl, fetch }` for staging, custom HTTP
+`authenticate()` also accepts `{ baseUrl, fetch }` for staging, custom HTTP
 transports, or a Node-`fetch` polyfill in legacy runtimes.
 ### Lower-level: hand-managed JWT
@@ -159,7 +159,7 @@ try {
 ## Cancellation
-Pass an `AbortSignal`. The SDK stops polling immediately and, if execution has already started server-side, best-effort calls `cancelExecution` on the QTSurfer API.
+Pass an `AbortSignal`. The SDK stops polling immediately and, if execution has already started server-side, best-effort calls `cancelBacktest` on the QTSurfer API.
 ```ts
 const controller = new AbortController();

package/dist/index.d.ts CHANGED Viewed

@@ -20,9 +20,15 @@ interface BacktestProgress {
     stage: BacktestStage;
     /** 0-100 when size is known. Undefined during stage start. */
     percent?: number;
+    /**
+     * Fraction (0-1) of the requested prepare window that actually holds data,
+     * reported by the backend once preparation completes. Present only on the
+     * final `preparing` event.
+     */
+    coverageRatio?: number;
 }
 interface BacktestOptions {
-    /** Abort the workflow. Cancels the current poll and calls `cancelExecution` server-side if execution has started. */
+    /** Abort the workflow. Cancels the current poll and calls `cancelBacktest` server-side if execution has started. */
     signal?: AbortSignal;
     /** Called on stage transitions and after each poll with updated progress. */
     onProgress?: (p: BacktestProgress) => void;
@@ -88,7 +94,7 @@ 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
+ * Thrown by the `authenticate()` helper when the apikey is missing or the JWT
  * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).
  */
 declare class QTSAuthError extends QTSError {
@@ -103,7 +109,7 @@ declare class QTSAuthError extends QTSError {
  * 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,
+ * token (if any), {@link save} after every successful `authenticate()` / refresh,
  * and {@link clear} when the session is explicitly invalidated.
  */
 interface TokenStore {
@@ -136,7 +142,7 @@ interface AuthOptions {
 /**
  * Authenticated SDK session.
  *
- * Returned by {@link auth}. Wraps the underlying api-client, owns a JWT
+ * Returned by {@link authenticate}. 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.
  *
@@ -183,6 +189,6 @@ declare class AuthenticatedClient {
  *
  * @throws {QTSAuthError} if no apikey is supplied or available in env.
  */
-declare function auth(apikey?: string, opts?: AuthOptions): Promise<AuthenticatedClient>;
+declare function authenticate(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 };
+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, authenticate };

package/dist/index.js CHANGED Viewed

@@ -3,13 +3,13 @@ import { client as apiClient } from "@qtsurfer/api-client";
 // src/workflows/backtest.ts
 import {
-  cancelExecution,
-  executeBacktesting,
-  getExecutionResult,
-  getPreparationStatus,
-  getStrategyStatus,
-  postStrategy,
-  prepareBacktesting
+  cancelBacktest,
+  executeBacktest,
+  getBacktestResult,
+  getPrepareStatus,
+  getStrategy,
+  compileStrategy as apiCompileStrategy,
+  prepareBacktest
 } from "@qtsurfer/api-client";
 import {
   ExponentialBackoff,
@@ -113,7 +113,7 @@ function buildStagePolicy(opts) {
   return opts.timeoutMs ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy) : retryPolicy;
 }
 async function compileStrategy(source, policy, opts) {
-  const { data, error } = await postStrategy({
+  const { data, error } = await apiCompileStrategy({
     body: source,
     headers: { "X-Compile-Async": true },
     ...opts.signal ? { signal: opts.signal } : {}
@@ -131,7 +131,7 @@ async function compileStrategy(source, policy, opts) {
     policy,
     opts,
     async ({ signal }) => {
-      const res = await getStrategyStatus({ path: { strategyId: compileJobId }, signal });
+      const res = await getStrategy({ path: { strategyId: compileJobId }, signal });
       if (res.error) throw new QTSStrategyCompileError("Compile status request failed", res.error);
       if (!res.data) throw new QTSStrategyCompileError("Empty compile status response");
       return res.data;
@@ -150,7 +150,7 @@ async function compileStrategy(source, policy, opts) {
   return status.strategyId;
 }
 async function prepareData(req, policy, opts) {
-  const { data, error } = await prepareBacktesting({
+  const { data, error } = await prepareBacktest({
     path: { exchangeId: req.exchangeId, type: TICKER },
     body: { instrument: req.instrument, from: req.from, to: req.to },
     ...opts.signal ? { signal: opts.signal } : {}
@@ -162,7 +162,7 @@ async function prepareData(req, policy, opts) {
     policy,
     opts,
     async ({ signal }) => {
-      const res = await getPreparationStatus({
+      const res = await getPrepareStatus({
         path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },
         signal
       });
@@ -183,10 +183,11 @@ async function prepareData(req, policy, opts) {
   if (prepNorm === "aborted") {
     throw new QTSCanceledError("Data preparation aborted");
   }
+  opts.onProgress?.({ stage: "preparing", percent: 100, coverageRatio: state.coverageRatio });
   return prepareJobId;
 }
 async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
-  const { data, error } = await executeBacktesting({
+  const { data, error } = await executeBacktest({
     path: { exchangeId: req.exchangeId, type: TICKER },
     body: {
       prepareJobId,
@@ -203,7 +204,7 @@ async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
       policy,
       opts,
       async ({ signal }) => {
-        const res = await getExecutionResult({
+        const res = await getBacktestResult({
           path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
           signal
         });
@@ -227,7 +228,7 @@ async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
     return finalResult.__result;
   } catch (err) {
     if (err instanceof QTSCanceledError) {
-      await cancelExecution({
+      await cancelBacktest({
         path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId }
       }).catch(() => void 0);
     }
@@ -256,12 +257,12 @@ async function runStage(policy, opts, fetchFn, onEachAttempt) {
 // src/workflows/downloads.ts
 import {
-  getExchangeKlinesHour,
-  getExchangeTickersHour
+  downloadKlines as apiDownloadKlines,
+  downloadTickers as apiDownloadTickers
 } from "@qtsurfer/api-client";
 async function downloadTickers(params) {
   const { exchangeId, base, quote, hour, format } = params;
-  const { data, error, response } = await getExchangeTickersHour({
+  const { data, error, response } = await apiDownloadTickers({
     path: { exchangeId, base, quote },
     query: { hour, ...format ? { format } : {} }
   });
@@ -276,7 +277,7 @@ async function downloadTickers(params) {
 }
 async function downloadKlines(params) {
   const { exchangeId, base, quote, hour, format } = params;
-  const { data, error, response } = await getExchangeKlinesHour({
+  const { data, error, response } = await apiDownloadKlines({
     path: { exchangeId, base, quote },
     query: { hour, ...format ? { format } : {} }
   });
@@ -332,7 +333,7 @@ var QTSurfer = class {
 // src/auth/session.ts
 import {
-  auth as apiAuth,
+  authenticate as apiAuth,
   client as apiClient2
 } from "@qtsurfer/api-client";
@@ -381,7 +382,7 @@ var AuthenticatedClient = class {
       });
       if (error || !data) {
         throw new QTSAuthError(
-          `auth() failed: HTTP ${response.status}`,
+          `authenticate() failed: HTTP ${response.status}`,
           error
         );
       }
@@ -448,11 +449,11 @@ var AuthenticatedClient = class {
     return this.withRefreshOn401(() => downloadKlines(args));
   }
 };
-async function auth(apikey, opts = {}) {
+async function authenticate(apikey, opts = {}) {
   const resolved = apikey ?? readEnvApikey();
   if (!resolved) {
     throw new QTSAuthError(
-      `auth() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`
+      `authenticate() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`
     );
   }
   const session = new AuthenticatedClient(resolved, opts);
@@ -482,6 +483,6 @@ export {
   QTSStrategyCompileError,
   QTSTimeoutError,
   QTSurfer,
-  auth
+  authenticate
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +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 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"]}
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":";AAAA,SAAS,UAAU,iBAAiB;;;ACApC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,mBAAmB;AAAA,EACnB;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;;;ACrBA,IAAM,WAAN,cAAuB,MAAM;AAAA,EAGlC,YAAY,SAA0B,OAAiB,QAAiB;AACtE,UAAM,OAAO;AADuB;AAEpC,SAAK,OAAO;AACZ,QAAI,WAAW,OAAW,MAAK,SAAS;AAAA,EAC1C;AAAA,EAJsC;AAAA;AAAA,EAD7B;AAMX;AAEO,IAAM,0BAAN,cAAsC,SAAS;AAAA,EACpD,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,sBAAN,cAAkC,SAAS;AAAA,EAChD,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,oBAAN,cAAgC,SAAS;AAAA,EAC9C,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,kBAAN,cAA8B,SAAS;AAAA,EAC5C,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,mBAAN,cAA+B,SAAS;AAAA,EAC7C,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,mBAAN,cAA+B,SAAS;AAAA,EAC7C,YAAY,SAAiB,OAAiB,QAAiB;AAC7D,UAAM,SAAS,OAAO,MAAM;AAC5B,SAAK,OAAO;AAAA,EACd;AACF;AAMO,IAAM,eAAN,cAA2B,SAAS;AAAA,EACzC,YAAY,SAAiB,OAAiB;AAC5C,UAAM,SAAS,KAAK;AACpB,SAAK,OAAO;AAAA,EACd;AACF;;;ADaA,IAAM,SAAyB;AAW/B,SAAS,gBAAgB,KAAgC;AACvD,QAAM,QAAQ,OAAO,QAAQ,WAAW,IAAI,YAAY,IAAI;AAC5D,MAAI,UAAU,YAAa,QAAO;AAClC,MAAI,UAAU,SAAU,QAAO;AAC/B,MAAI,UAAU,aAAa,UAAU,eAAe,UAAU,YAAY;AACxE,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEA,eAAsB,SACpB,KACA,OAAwB,CAAC,GACA;AACzB,QAAM,SAAS,iBAAiB,IAAI;AAGpC,OAAK,aAAa,EAAE,OAAO,YAAY,CAAC;AACxC,QAAM,aAAa,MAAM,gBAAgB,IAAI,UAAU,QAAQ,IAAI;AAGnE,OAAK,aAAa,EAAE,OAAO,YAAY,CAAC;AACxC,QAAM,eAAe,MAAM,YAAY,KAAK,QAAQ,IAAI;AAGxD,OAAK,aAAa,EAAE,OAAO,YAAY,CAAC;AACxC,SAAO,gBAAgB,KAAK,cAAc,YAAY,QAAQ,IAAI;AACpE;AAEA,SAAS,iBAAiB,MAA6D;AACrF,QAAM,cAAc;AAAA,IAClB,iBAAiB,CAAC,MAAM;AACtB,YAAM,SAAU,GAAwC;AACxD,aAAO,gBAAgB,MAAM,MAAM;AAAA,IACrC,CAAC;AAAA,IACD;AAAA,MACE,aAAa,OAAO;AAAA,MACpB,SAAS,IAAI,mBAAmB;AAAA,QAC9B,cAAc,KAAK,kBAAkB;AAAA,QACrC,UAAU,KAAK,qBAAqB;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO,KAAK,YACR,KAAK,QAAQ,KAAK,WAAW,gBAAgB,WAAW,GAAG,WAAW,IACtE;AACN;AAEA,eAAe,gBACb,QACA,QACA,MACiB;AACjB,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,mBAAmB;AAAA,IAC/C,MAAM;AAAA,IACN,SAAS,EAAE,mBAAmB,KAAK;AAAA,IACnC,GAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;AAAA,EAC/C,CAAC;AACD,MAAI,MAAO,OAAM,IAAI,wBAAwB,8BAA8B,KAAK;AAChF,MAAI,CAAC,KAAM,OAAM,IAAI,wBAAwB,uCAAuC;AAGpF,MAAI,gBAAgB,QAAQ,KAAK,YAAY;AAC3C,WAAO,KAAK;AAAA,EACd;AACA,MAAI,EAAE,WAAW,SAAS,CAAC,KAAK,OAAO;AACrC,UAAM,IAAI,wBAAwB,8CAA8C;AAAA,EAClF;AAEA,QAAM,eAAe,KAAK;AAC1B,QAAM,SAAS,MAAM;AAAA,IACnB;AAAA,IACA;AAAA,IACA,OAAO,EAAE,OAAO,MAAM;AACpB,YAAM,MAAM,MAAM,YAAY,EAAE,MAAM,EAAE,YAAY,aAAa,GAAG,OAAO,CAAC;AAC5E,UAAI,IAAI,MAAO,OAAM,IAAI,wBAAwB,iCAAiC,IAAI,KAAK;AAC3F,UAAI,CAAC,IAAI,KAAM,OAAM,IAAI,wBAAwB,+BAA+B;AAChF,aAAO,IAAI;AAAA,IACb;AAAA,EACF;AAEA,QAAM,OAAO,gBAAgB,OAAO,MAAM;AAC1C,MAAI,SAAS,UAAU;AACrB,UAAM,IAAI,wBAAwB,OAAO,gBAAgB,6BAA6B;AAAA,EACxF;AACA,MAAI,SAAS,WAAW;AACtB,UAAM,IAAI,iBAAiB,8BAA8B;AAAA,EAC3D;AACA,MAAI,CAAC,OAAO,YAAY;AACtB,UAAM,IAAI,wBAAwB,wCAAwC;AAAA,EAC5E;AACA,SAAO,OAAO;AAChB;AAEA,eAAe,YACb,KACA,QACA,MACiB;AACjB,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,gBAAgB;AAAA,IAC5C,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,OAAO;AAAA,IACjD,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,IAAI,MAAM,IAAI,IAAI,GAAG;AAAA,IAC/D,GAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;AAAA,EAC/C,CAAC;AACD,MAAI,MAAO,OAAM,IAAI,oBAAoB,6BAA6B,KAAK;AAC3E,MAAI,CAAC,MAAM,MAAO,OAAM,IAAI,oBAAoB,mCAAmC;AAEnF,QAAM,eAAe,KAAK;AAC1B,QAAM,QAAQ,MAAM;AAAA,IAClB;AAAA,IACA;AAAA,IACA,OAAO,EAAE,OAAO,MAAM;AACpB,YAAM,MAAM,MAAM,iBAAiB;AAAA,QACjC,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,QAAQ,OAAO,aAAa;AAAA,QACtE;AAAA,MACF,CAAC;AACD,UAAI,IAAI,MAAO,OAAM,IAAI,oBAAoB,qCAAqC,IAAI,KAAK;AAC3F,UAAI,CAAC,IAAI,KAAM,OAAM,IAAI,oBAAoB,mCAAmC;AAChF,aAAO,IAAI;AAAA,IACb;AAAA,IACA,CAAC,MAAM;AACL,UAAI,EAAE,OAAO,GAAG;AACd,aAAK,aAAa,EAAE,OAAO,aAAa,SAAU,EAAE,YAAY,EAAE,OAAQ,IAAI,CAAC;AAAA,MACjF;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAW,gBAAgB,MAAM,MAAM;AAC7C,MAAI,aAAa,UAAU;AACzB,UAAM,IAAI,oBAAoB,MAAM,gBAAgB,yBAAyB;AAAA,EAC/E;AACA,MAAI,aAAa,WAAW;AAC1B,UAAM,IAAI,iBAAiB,0BAA0B;AAAA,EACvD;AAGA,OAAK,aAAa,EAAE,OAAO,aAAa,SAAS,KAAK,eAAe,MAAM,cAAc,CAAC;AAC1F,SAAO;AACT;AAEA,eAAe,gBACb,KACA,cACA,YACA,QACA,MACyB;AACzB,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,gBAAgB;AAAA,IAC5C,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,OAAO;AAAA,IACjD,MAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA,GAAI,IAAI,iBAAiB,SAAY,EAAE,cAAc,IAAI,aAAa,IAAI,CAAC;AAAA,IAC7E;AAAA,IACA,GAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;AAAA,EAC/C,CAAC;AACD,MAAI,MAAO,OAAM,IAAI,kBAAkB,6BAA6B,KAAK;AACzE,MAAI,CAAC,MAAM,MAAO,OAAM,IAAI,kBAAkB,mCAAmC;AAEjF,QAAM,eAAe,KAAK;AAE1B,MAAI;AACF,UAAM,cAAc,MAAM;AAAA,MACxB;AAAA,MACA;AAAA,MACA,OAAO,EAAE,OAAO,MAAM;AACpB,cAAM,MAAM,MAAM,kBAAkB;AAAA,UAClC,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,QAAQ,OAAO,aAAa;AAAA,UACtE;AAAA,QACF,CAAC;AACD,YAAI,IAAI,MAAO,OAAM,IAAI,kBAAkB,mCAAmC,IAAI,KAAK;AACvF,YAAI,CAAC,IAAI,KAAM,OAAM,IAAI,kBAAkB,iCAAiC;AAC5E,eAAO,EAAE,GAAG,IAAI,KAAK,OAAO,UAAU,IAAI,KAAK,QAAQ;AAAA,MACzD;AAAA,MACA,CAAC,MAAM;AACL,YAAI,EAAE,OAAO,GAAG;AACd,eAAK,aAAa,EAAE,OAAO,aAAa,SAAU,EAAE,YAAY,EAAE,OAAQ,IAAI,CAAC;AAAA,QACjF;AAAA,MACF;AAAA,IACF;AAEA,UAAM,WAAW,gBAAgB,YAAY,MAAM;AACnD,QAAI,aAAa,UAAU;AACzB,YAAM,IAAI,kBAAkB,YAAY,gBAAgB,kBAAkB;AAAA,IAC5E;AACA,QAAI,aAAa,WAAW;AAC1B,YAAM,IAAI,iBAAiB,mBAAmB;AAAA,IAChD;AACA,WAAO,YAAY;AAAA,EACrB,SAAS,KAAK;AACZ,QAAI,eAAe,kBAAkB;AACnC,YAAM,eAAe;AAAA,QACnB,MAAM,EAAE,YAAY,IAAI,YAAY,MAAM,QAAQ,OAAO,aAAa;AAAA,MACxE,CAAC,EAAE,MAAM,MAAM,MAAS;AAAA,IAC1B;AACA,UAAM;AAAA,EACR;AACF;AAEA,eAAe,SACb,QACA,MACA,SACA,eACY;AACZ,MAAI;AACF,WAAO,MAAM,OAAO,QAAQ,OAAO,QAAQ;AACzC,UAAI,KAAK,QAAQ,QAAS,OAAM,IAAI,iBAAiB,kBAAkB;AACvE,YAAM,SAAS,MAAM,QAAQ,GAAG;AAChC,sBAAgB,MAAM;AACtB,UAAI,KAAK,QAAQ,QAAS,OAAM,IAAI,iBAAiB,kBAAkB;AACvE,aAAO;AAAA,IACT,GAAG,KAAK,MAAM;AAAA,EAChB,SAAS,KAAK;AACZ,QAAI,eAAe,iBAAkB,OAAM;AAC3C,QAAI,eAAe,oBAAoB;AACrC,UAAI,KAAK,QAAQ,QAAS,OAAM,IAAI,iBAAiB,oBAAoB,GAAG;AAC5E,YAAM,IAAI,gBAAgB,kBAAkB,KAAK,SAAS,MAAM,GAAG;AAAA,IACrE;AACA,QAAI,KAAK,QAAQ,QAAS,OAAM,IAAI,iBAAiB,oBAAoB,GAAG;AAC5E,UAAM;AAAA,EACR;AACF;;;AErTA;AAAA,EACE,kBAAkB;AAAA,EAClB,mBAAmB;AAAA,OACd;AAwBP,eAAsB,gBAAgB,QAAuC;AAC3E,QAAM,EAAE,YAAY,MAAM,OAAO,MAAM,OAAO,IAAI;AAClD,QAAM,EAAE,MAAM,OAAO,SAAS,IAAI,MAAM,mBAAmB;AAAA,IACzD,MAAM,EAAE,YAAY,MAAM,MAAM;AAAA,IAChC,OAAO,EAAE,MAAM,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC,EAAG;AAAA,EAC/C,CAAC;AACD,MAAI,OAAO;AACT,UAAM,IAAI;AAAA,MACR,iCAAiC,SAAS,MAAM,WAAM,SAAS,KAAK,CAAC;AAAA,MACrE;AAAA,MACA,SAAS;AAAA,IACX;AAAA,EACF;AACA,SAAO;AACT;AAQA,eAAsB,eAAe,QAAuC;AAC1E,QAAM,EAAE,YAAY,MAAM,OAAO,MAAM,OAAO,IAAI;AAClD,QAAM,EAAE,MAAM,OAAO,SAAS,IAAI,MAAM,kBAAkB;AAAA,IACxD,MAAM,EAAE,YAAY,MAAM,MAAM;AAAA,IAChC,OAAO,EAAE,MAAM,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC,EAAG;AAAA,EAC/C,CAAC;AACD,MAAI,OAAO;AACT,UAAM,IAAI;AAAA,MACR,gCAAgC,SAAS,MAAM,WAAM,SAAS,KAAK,CAAC;AAAA,MACpE;AAAA,MACA,SAAS;AAAA,IACX;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,SAAS,OAAwB;AACxC,MAAI,SAAS,OAAO,UAAU,UAAU;AACtC,UAAM,IAAI;AACV,UAAM,OAAO,OAAO,EAAE,SAAS,WAAW,EAAE,OAAO;AACnD,UAAM,UAAU,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU;AAC5D,QAAI,QAAQ,QAAS,QAAO,GAAG,IAAI,KAAK,OAAO;AAC/C,QAAI,QAAS,QAAO;AACpB,QAAI,KAAM,QAAO;AAAA,EACnB;AACA,SAAO,OAAO,KAAK;AACrB;;;AH9CO,IAAM,WAAN,MAAe;AAAA,EACpB,YAAY,SAA0B;AACpC,cAAU,UAAU;AAAA,MAClB,SAAS,QAAQ;AAAA,MACjB,GAAI,QAAQ,QACR,EAAE,SAAS,EAAE,eAAe,UAAU,QAAQ,KAAK,GAAG,EAAE,IACxD,CAAC;AAAA,MACL,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA,IAClD,CAAC;AAAA,EACH;AAAA,EAEA,SAAS,KAAsB,MAAiD;AAC9E,WAAO,SAAS,KAAK,IAAI;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAQ,MAAuC;AAC7C,WAAO,gBAAgB,IAAI;AAAA,EAC7B;AAAA;AAAA,EAGA,OAAO,MAAuC;AAC5C,WAAO,eAAe,IAAI;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAMF;;;AI7DA;AAAA,EACE,gBAAgB;AAAA,EAChB,UAAUA;AAAA,OAEL;;;ACsBA,IAAM,qBAAN,MAA+C;AAAA,EAC5C,QAAkC;AAAA,EAE1C,OAAiC;AAC/B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,KAAK,OAAgC;AACnC,SAAK,QAAQ;AAAA,EACf;AAAA,EAEA,QAAc;AACZ,SAAK,QAAQ;AAAA,EACf;AACF;;;ADrBA,IAAM,iBAAiB;AACvB,IAAM,mBAAmB;AAsBlB,IAAM,sBAAN,MAA0B;AAAA,EACtB;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACT,SAAmC;AAAA,EACnC,aAAgD;AAAA,EAExD,YAAY,QAAgB,OAAoB,CAAC,GAAG;AAClD,SAAK,SAAS;AACd,SAAK,UAAU,KAAK,WAAW;AAC/B,SAAK,QAAQ,KAAK,SAAS,IAAI,mBAAmB;AAClD,SAAK,YAAY,KAAK;AAAA,EACxB;AAAA;AAAA,EAGA,IAAI,QAAkC;AACpC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,MAAM,UAAsC;AAC1C,QAAI,KAAK,WAAY,QAAO,KAAK;AACjC,SAAK,cAAc,YAAY;AAC7B,YAAM,EAAE,MAAM,OAAO,SAAS,IAAI,MAAM,QAAQ;AAAA,QAC9C,SAAS,KAAK;AAAA,QACd,SAAS,EAAE,aAAa,KAAK,OAAO;AAAA,QACpC,GAAI,KAAK,YAAY,EAAE,OAAO,KAAK,UAAU,IAAI,CAAC;AAAA,MACpD,CAAC;AACD,UAAI,SAAS,CAAC,MAAM;AAClB,cAAM,IAAI;AAAA,UACR,+BAA+B,SAAS,MAAM;AAAA,UAC9C;AAAA,QACF;AAAA,MACF;AACA,WAAK,SAAS;AACd,YAAM,KAAK,MAAM,KAAK,IAAI;AAC1B,aAAO;AAAA,IACT,GAAG;AACH,QAAI;AACF,aAAO,MAAM,KAAK;AAAA,IACpB,UAAE;AACA,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,cAA0C;AAC9C,QAAI,KAAK,OAAQ,QAAO,KAAK;AAC7B,UAAM,SAAS,MAAM,KAAK,MAAM,KAAK;AACrC,QAAI,QAAQ;AACV,WAAK,SAAS;AACd,aAAO;AAAA,IACT;AACA,WAAO,KAAK,QAAQ;AAAA,EACtB;AAAA;AAAA,EAGA,MAAM,QAAuB;AAC3B,SAAK,SAAS;AACd,UAAM,KAAK,MAAM,MAAM;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,iBAAoB,MAAoC;AACpE,UAAM,KAAK,YAAY;AACvB,QAAI;AACF,aAAO,MAAM,KAAK;AAAA,IACpB,SAAS,KAAK;AACZ,UAAI,CAAC,eAAe,GAAG,EAAG,OAAM;AAChC,WAAK,SAAS;AACd,YAAM,KAAK,QAAQ;AACnB,YAAM,KAAK,YAAY;AACvB,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AAAA,EAEA,MAAc,cAA6B;AACzC,UAAM,QAAQ,MAAM,KAAK,YAAY;AACrC,IAAAC,WAAU,UAAU;AAAA,MAClB,SAAS,KAAK;AAAA,MACd,SAAS,EAAE,eAAe,UAAU,MAAM,YAAY,GAAG;AAAA,MACzD,GAAI,KAAK,YAAY,EAAE,OAAO,KAAK,UAAU,IAAI,CAAC;AAAA,IACpD,CAAC;AAAA,EACH;AAAA;AAAA,EAIA,SAAS,KAAsB,MAAiD;AAC9E,WAAO,KAAK,iBAAiB,MAAM,SAAY,KAAK,IAAI,CAAC;AAAA,EAC3D;AAAA,EAEA,QAAQ,MAAuC;AAC7C,WAAO,KAAK,iBAAiB,MAAM,gBAAgB,IAAI,CAAC;AAAA,EAC1D;AAAA,EAEA,OAAO,MAAuC;AAC5C,WAAO,KAAK,iBAAiB,MAAM,eAAe,IAAI,CAAC;AAAA,EACzD;AACF;AAYA,eAAsB,aACpB,QACA,OAAoB,CAAC,GACS;AAC9B,QAAM,WAAW,UAAU,cAAc;AACzC,MAAI,CAAC,UAAU;AACb,UAAM,IAAI;AAAA,MACR,kDAAkD,cAAc;AAAA,IAClE;AAAA,EACF;AACA,QAAM,UAAU,IAAI,oBAAoB,UAAU,IAAI;AACtD,QAAM,QAAQ,YAAY;AAC1B,SAAO;AACT;AAEA,SAAS,gBAAoC;AAE3C,MAAI,OAAO,YAAY,eAAe,CAAC,QAAQ,IAAK,QAAO;AAC3D,QAAM,QAAQ,QAAQ,IAAI,cAAc;AACxC,SAAO,SAAS,MAAM,SAAS,IAAI,QAAQ;AAC7C;AAEA,SAAS,eAAe,KAAuB;AAC7C,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAI5C,QAAM,cAAe,IAA6B;AAClD,MAAI,OAAO,gBAAgB,YAAY,gBAAgB,IAAK,QAAO;AACnE,SAAO;AACT;","names":["apiClient","apiClient"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@qtsurfer/sdk",
-  "version": "0.4.0",
+  "version": "0.6.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.3.0",
+    "@qtsurfer/api-client": "^0.5.0",
     "cockatiel": "^3.2.1"
   },
   "devDependencies": {

package/src/auth/session.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import {
-  auth as apiAuth,
+  authenticate as apiAuth,
   client as apiClient,
   type AuthTokenResponse,
 } from '@qtsurfer/api-client';
@@ -32,7 +32,7 @@ export interface AuthOptions {
 /**
  * Authenticated SDK session.
  *
- * Returned by {@link auth}. Wraps the underlying api-client, owns a JWT
+ * Returned by {@link authenticate}. 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.
  *
@@ -71,7 +71,7 @@ export class AuthenticatedClient {
       });
       if (error || !data) {
         throw new QTSAuthError(
-          `auth() failed: HTTP ${response.status}`,
+          `authenticate() failed: HTTP ${response.status}`,
           error,
         );
       }
@@ -157,14 +157,14 @@ export class AuthenticatedClient {
  *
  * @throws {QTSAuthError} if no apikey is supplied or available in env.
  */
-export async function auth(
+export async function authenticate(
   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)`,
+      `authenticate() requires an apikey (argument or ${APIKEY_ENV_VAR} env var)`,
     );
   }
   const session = new AuthenticatedClient(resolved, opts);

package/src/auth/tokenStore.ts CHANGED Viewed

@@ -8,7 +8,7 @@ import type { AuthTokenResponse } from '@qtsurfer/api-client';
  * 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,
+ * token (if any), {@link save} after every successful `authenticate()` / refresh,
  * and {@link clear} when the session is explicitly invalidated.
  */
 export interface TokenStore {

package/src/errors.ts CHANGED Viewed

@@ -51,7 +51,7 @@ export class QTSDownloadError extends QTSError {
 }
 /**
- * Thrown by the `auth()` helper when the apikey is missing or the JWT
+ * Thrown by the `authenticate()` helper when the apikey is missing or the JWT
  * exchange fails (HTTP 401 from `POST /v1/auth/token`, etc.).
  */
 export class QTSAuthError extends QTSError {

package/src/index.ts CHANGED Viewed

@@ -18,7 +18,7 @@ export type {
 } from './workflows/backtest';
 export type { DownloadFormat } from './workflows/downloads';
 export {
-  auth,
+  authenticate,
   AuthenticatedClient,
   type AuthOptions,
 } from './auth/session';

package/src/workflows/backtest.ts CHANGED Viewed

@@ -1,11 +1,11 @@
 import {
-  cancelExecution,
-  executeBacktesting,
-  getExecutionResult,
-  getPreparationStatus,
-  getStrategyStatus,
-  postStrategy,
-  prepareBacktesting,
+  cancelBacktest,
+  executeBacktest,
+  getBacktestResult,
+  getPrepareStatus,
+  getStrategy,
+  compileStrategy as apiCompileStrategy,
+  prepareBacktest,
   type DataSourceType,
   type ResultMap,
 } from '@qtsurfer/api-client';
@@ -51,10 +51,16 @@ export interface BacktestProgress {
   stage: BacktestStage;
   /** 0-100 when size is known. Undefined during stage start. */
   percent?: number;
+  /**
+   * Fraction (0-1) of the requested prepare window that actually holds data,
+   * reported by the backend once preparation completes. Present only on the
+   * final `preparing` event.
+   */
+  coverageRatio?: number;
 }
 export interface BacktestOptions {
-  /** Abort the workflow. Cancels the current poll and calls `cancelExecution` server-side if execution has started. */
+  /** Abort the workflow. Cancels the current poll and calls `cancelBacktest` server-side if execution has started. */
   signal?: AbortSignal;
   /** Called on stage transitions and after each poll with updated progress. */
   onProgress?: (p: BacktestProgress) => void;
@@ -68,7 +74,7 @@ export interface BacktestOptions {
 const TICKER: DataSourceType = 'ticker';
-type JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed' | 'Partial';
+type JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
 /**
  * Normalize the backend job status to a stable lowercase form so we can
@@ -132,7 +138,7 @@ async function compileStrategy(
   policy: IPolicy<ICancellationContext, never>,
   opts: BacktestOptions,
 ): Promise<string> {
-  const { data, error } = await postStrategy({
+  const { data, error } = await apiCompileStrategy({
     body: source,
     headers: { 'X-Compile-Async': true },
     ...(opts.signal ? { signal: opts.signal } : {}),
@@ -153,7 +159,7 @@ async function compileStrategy(
     policy,
     opts,
     async ({ signal }) => {
-      const res = await getStrategyStatus({ path: { strategyId: compileJobId }, signal });
+      const res = await getStrategy({ path: { strategyId: compileJobId }, signal });
       if (res.error) throw new QTSStrategyCompileError('Compile status request failed', res.error);
       if (!res.data) throw new QTSStrategyCompileError('Empty compile status response');
       return res.data;
@@ -178,7 +184,7 @@ async function prepareData(
   policy: IPolicy<ICancellationContext, never>,
   opts: BacktestOptions,
 ): Promise<string> {
-  const { data, error } = await prepareBacktesting({
+  const { data, error } = await prepareBacktest({
     path: { exchangeId: req.exchangeId, type: TICKER },
     body: { instrument: req.instrument, from: req.from, to: req.to },
     ...(opts.signal ? { signal: opts.signal } : {}),
@@ -191,7 +197,7 @@ async function prepareData(
     policy,
     opts,
     async ({ signal }) => {
-      const res = await getPreparationStatus({
+      const res = await getPrepareStatus({
         path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },
         signal,
       });
@@ -213,6 +219,9 @@ async function prepareData(
   if (prepNorm === 'aborted') {
     throw new QTSCanceledError('Data preparation aborted');
   }
+  // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the
+  // final preparing event, so callers can react to a partially-covered range.
+  opts.onProgress?.({ stage: 'preparing', percent: 100, coverageRatio: state.coverageRatio });
   return prepareJobId;
 }
@@ -223,7 +232,7 @@ async function executeStrategy(
   policy: IPolicy<ICancellationContext, never>,
   opts: BacktestOptions,
 ): Promise<BacktestResult> {
-  const { data, error } = await executeBacktesting({
+  const { data, error } = await executeBacktest({
     path: { exchangeId: req.exchangeId, type: TICKER },
     body: {
       prepareJobId,
@@ -242,7 +251,7 @@ async function executeStrategy(
       policy,
       opts,
       async ({ signal }) => {
-        const res = await getExecutionResult({
+        const res = await getBacktestResult({
           path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
           signal,
         });
@@ -267,7 +276,7 @@ async function executeStrategy(
     return finalResult.__result;
   } catch (err) {
     if (err instanceof QTSCanceledError) {
-      await cancelExecution({
+      await cancelBacktest({
         path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
       }).catch(() => undefined);
     }

package/src/workflows/downloads.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import {
-  getExchangeKlinesHour,
-  getExchangeTickersHour,
+  downloadKlines as apiDownloadKlines,
+  downloadTickers as apiDownloadTickers,
 } from '@qtsurfer/api-client';
 import { QTSDownloadError } from '../errors';
@@ -27,7 +27,7 @@ export interface DownloadParams {
  */
 export async function downloadTickers(params: DownloadParams): Promise<Blob> {
   const { exchangeId, base, quote, hour, format } = params;
-  const { data, error, response } = await getExchangeTickersHour({
+  const { data, error, response } = await apiDownloadTickers({
     path: { exchangeId, base, quote },
     query: { hour, ...(format ? { format } : {}) },
   });
@@ -49,7 +49,7 @@ export async function downloadTickers(params: DownloadParams): Promise<Blob> {
  */
 export async function downloadKlines(params: DownloadParams): Promise<Blob> {
   const { exchangeId, base, quote, hour, format } = params;
-  const { data, error, response } = await getExchangeKlinesHour({
+  const { data, error, response } = await apiDownloadKlines({
     path: { exchangeId, base, quote },
     query: { hour, ...(format ? { format } : {}) },
   });