@qtsurfer/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 QTSurfer
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,160 @@
+# @qtsurfer/sdk
+
+<p align="center">
+  <a href="https://github.com/QTSurfer/sdk-ts/actions/workflows/ci.yml"><img src="https://github.com/QTSurfer/sdk-ts/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@qtsurfer/sdk"><img src="https://img.shields.io/npm/v/@qtsurfer/sdk" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
+</p>
+
+Opinionated TypeScript SDK for [QTSurfer](https://qtsurfer.com), built on top of [`@qtsurfer/api-client`](https://github.com/QTSurfer/api-client-ts).
+
+Where `@qtsurfer/api-client` gives you one typed function per API endpoint, `@qtsurfer/sdk` adds **workflow orchestration**, **normalized errors**, and **cancellation** — run a backtest with a single `await`.
+
+## Installation
+
+```bash
+npm install @qtsurfer/sdk
+# or
+pnpm add @qtsurfer/sdk
+```
+
+## Quick start
+
+```ts
+import { QTSurfer } 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();
+
+const result = await qts.backtest(
+  {
+    strategy: readFileSync('./MyStrategy.java', 'utf8'),
+    exchangeId: 'binance',
+    instrument: 'BTCUSDT',
+    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,
+  },
+);
+
+console.log('PnL:', result.pnlTotal);
+console.log('Trades:', result.totalTrades);
+console.log('Signals:', result.signalsUrl);
+```
+
+## What `backtest()` does
+
+Orchestrates the full four-step workflow that the raw API exposes:
+
+1. **Compile** the strategy (`POST /strategy` in async mode) and poll `GET /strategy/{id}` until `Completed`.
+2. **Prepare** the data range (`POST /backtest/{exchange}/ticker/prepare`) and poll until `Completed`.
+3. **Execute** the backtest (`POST /backtest/{exchange}/ticker/execute`) and poll `GET /backtest/.../execute/{jobId}` until `Completed`.
+4. Return the `ResultMap` (`pnlTotal`, `totalTrades`, `sharpeRatio`, `signalsUrl`, …).
+
+Polling uses exponential backoff (`intervalMs * 1.5`, capped at `maxIntervalMs`) with per-stage timeout.
+
+Progress is emitted on every stage transition and after each poll whose `size > 0`.
+
+## Error hierarchy
+
+All SDK errors extend `QTSError` so you can catch them generically or match by subclass.
+
+```ts
+import {
+  QTSError,
+  QTSStrategyCompileError,
+  QTSPreparationError,
+  QTSExecutionError,
+  QTSTimeoutError,
+  QTSCanceledError,
+} from '@qtsurfer/sdk';
+
+try {
+  await qts.backtest(req);
+} catch (e) {
+  if (e instanceof QTSStrategyCompileError) {
+    console.error('Compile failed:', e.message);
+  } else if (e instanceof QTSPreparationError) {
+    console.error('Data prep failed:', e.message);
+  } else if (e instanceof QTSExecutionError) {
+    console.error('Execution failed:', e.message);
+  } else if (e instanceof QTSTimeoutError) {
+    console.error('Stage timed out');
+  } else if (e instanceof QTSCanceledError) {
+    console.error('Canceled by signal');
+  }
+}
+```
+
+## 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.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 60_000);
+await qts.backtest(req, { signal: controller.signal });
+```
+
+## Under the hood
+
+Polling, retry, backoff, timeout, and cancellation are delegated to [`cockatiel`](https://github.com/connor4312/cockatiel). Each workflow stage composes a `retry` policy (exponential backoff on in-progress statuses) with an optional `timeout` policy. If you need advanced resilience primitives (circuit breakers, bulkheads, fallbacks), import them directly from `cockatiel`.
+
+## Roadmap
+
+### v0.1 — Core workflow ✅
+
+- [x] `QTSurfer` client over `@qtsurfer/api-client`
+- [x] `qts.backtest()` orchestrating compile → prepare → execute
+- [x] Backoff, timeout, and `AbortSignal` cancellation via `cockatiel` policies
+- [x] Error hierarchy: `QTSError`, `QTSStrategyCompileError`, `QTSPreparationError`, `QTSExecutionError`, `QTSTimeoutError`, `QTSCanceledError`
+
+### v0.2 — Domain objects
+
+- [ ] `Strategy` class with `.backtest()`, `.status()`
+- [ ] `BacktestJob` class with `.wait()`, `.cancel()`, `.stream()`
+- [ ] TTL cache for `exchanges` / `instruments`
+
+### v0.3 — Streaming progress
+
+- [ ] `job.stream()` returns `AsyncIterator<BacktestProgress>`
+- [ ] Server-side hooks (when the backend exposes SSE/WebSocket)
+
+### v0.4 — Ecosystem integration
+
+- [ ] Helpers to load `signalsUrl` Parquet into DuckDB / Lastra
+- [ ] Framework adapters (`@qtsurfer/sdk-react`, `@qtsurfer/sdk-svelte`)
+
+## Project layout
+
+```
+src/
+├── index.ts              # public exports
+├── client.ts             # QTSurfer class
+├── errors.ts             # QTSError hierarchy
+└── workflows/
+    └── backtest.ts       # compile → prepare → execute (cockatiel policies)
+```
+
+## Development
+
+| Script | Description |
+| ------ | ----------- |
+| `npm run lint` | Type-check without emitting |
+| `npm run build` | Compile to `dist/` |
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { type BacktestOptions, type BacktestRequest, type BacktestResult } from './workflows/backtest';
+export interface QTSurferOptions {
+    baseUrl: string;
+    token?: string;
+    fetch?: typeof fetch;
+}
+export declare class QTSurfer {
+    constructor(options: QTSurferOptions);
+    backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,QAAQ;gBACP,OAAO,EAAE,eAAe;IAUpC,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAQhF"}

package/dist/client.js

@@ -0,0 +1,17 @@
+import { client as apiClient } from '@qtsurfer/api-client';
+import { backtest, } from './workflows/backtest';
+export class QTSurfer {
+    constructor(options) {
+        apiClient.setConfig({
+            baseUrl: options.baseUrl,
+            ...(options.token
+                ? { headers: { Authorization: `Bearer ${options.token}` } }
+                : {}),
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+    }
+    backtest(req, opts) {
+        return backtest(req, opts);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,QAAQ,GAIT,MAAM,sBAAsB,CAAC;AAQ9B,MAAM,OAAO,QAAQ;IACnB,YAAY,OAAwB;QAClC,SAAS,CAAC,SAAS,CAAC;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,CAAC,OAAO,CAAC,KAAK;gBACf,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE;gBAC3D,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,GAAoB,EAAE,IAAsB;QACnD,OAAO,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;CAMF"}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class QTSError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class QTSStrategyCompileError extends QTSError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class QTSPreparationError extends QTSError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class QTSExecutionError extends QTSError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class QTSTimeoutError extends QTSError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class QTSCanceledError extends QTSError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IACJ,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+export class QTSError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'QTSError';
+    }
+}
+export class QTSStrategyCompileError extends QTSError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'QTSStrategyCompileError';
+    }
+}
+export class QTSPreparationError extends QTSError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'QTSPreparationError';
+    }
+}
+export class QTSExecutionError extends QTSError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'QTSExecutionError';
+    }
+}
+export class QTSTimeoutError extends QTSError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'QTSTimeoutError';
+    }
+}
+export class QTSCanceledError extends QTSError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'QTSCanceledError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACK;IAAtC,YAAY,OAAe,EAAW,KAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,UAAK,GAAL,KAAK,CAAU;QAEnD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,QAAQ;IACnD,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IAC/C,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { QTSurfer, type QTSurferOptions } from './client';
+export { QTSError, QTSStrategyCompileError, QTSPreparationError, QTSExecutionError, QTSTimeoutError, QTSCanceledError, } from './errors';
+export type { BacktestRequest, BacktestResult, BacktestProgress, BacktestStage, BacktestOptions, } from './workflows/backtest';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { QTSurfer } from './client';
+export { QTSError, QTSStrategyCompileError, QTSPreparationError, QTSExecutionError, QTSTimeoutError, QTSCanceledError, } from './errors';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAwB,MAAM,UAAU,CAAC;AAC1D,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,UAAU,CAAC"}

package/dist/workflows/backtest.d.ts

@@ -0,0 +1,36 @@
+import { type ResultMap } from '@qtsurfer/api-client';
+export interface BacktestRequest {
+    /** Strategy source code (Java) */
+    strategy: string;
+    /** Exchange id, e.g. `binance` */
+    exchangeId: string;
+    /** Instrument symbol, e.g. `BTCUSDT` */
+    instrument: string;
+    /** Date range start (ISO-8601, ISO DATE or BASIC ISO DATE) */
+    from: string;
+    /** Date range end (same formats as `from`) */
+    to: string;
+    /** When true, the worker uploads emitted signals to object storage. */
+    storeSignals?: boolean;
+}
+export type BacktestResult = ResultMap;
+export type BacktestStage = 'compiling' | 'preparing' | 'executing';
+export interface BacktestProgress {
+    stage: BacktestStage;
+    /** 0-100 when size is known. Undefined during stage start. */
+    percent?: number;
+}
+export interface BacktestOptions {
+    /** Abort the workflow. Cancels the current poll and calls `cancelExecution` server-side if execution has started. */
+    signal?: AbortSignal;
+    /** Called on stage transitions and after each poll with updated progress. */
+    onProgress?: (p: BacktestProgress) => void;
+    /** Initial interval between polls. Default 500ms, backed off up to `maxPollIntervalMs`. */
+    pollIntervalMs?: number;
+    /** Upper bound for exponential backoff. Default 5000ms. */
+    maxPollIntervalMs?: number;
+    /** Per-stage timeout. Default none. */
+    timeoutMs?: number;
+}
+export declare function backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+//# sourceMappingURL=backtest.d.ts.map

package/dist/workflows/backtest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../../src/workflows/backtest.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAoB9B,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,qHAAqH;IACrH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3C,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,eAAe,EACpB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CAczB"}

package/dist/workflows/backtest.js

@@ -0,0 +1,168 @@
+import { cancelExecution, executeBacktesting, getExecutionResult, getPreparationStatus, getStrategyStatus, postStrategy, prepareBacktesting, } from '@qtsurfer/api-client';
+import { ExponentialBackoff, TaskCancelledError, TimeoutStrategy, handleWhenResult, retry, timeout, wrap, } from 'cockatiel';
+import { QTSCanceledError, QTSExecutionError, QTSPreparationError, QTSStrategyCompileError, QTSTimeoutError, } from '../errors';
+const TICKER = 'ticker';
+export async function backtest(req, opts = {}) {
+    const policy = buildStagePolicy(opts);
+    // 1. Compile strategy (async mode)
+    opts.onProgress?.({ stage: 'compiling' });
+    const strategyId = await compileStrategy(req.strategy, policy, opts);
+    // 2. Prepare data
+    opts.onProgress?.({ stage: 'preparing' });
+    const prepareJobId = await prepareData(req, policy, opts);
+    // 3. Execute
+    opts.onProgress?.({ stage: 'executing' });
+    return executeStrategy(req, prepareJobId, strategyId, policy, opts);
+}
+function buildStagePolicy(opts) {
+    const retryPolicy = retry(handleWhenResult((r) => {
+        const status = r?.status;
+        return status === 'New' || status === 'Started';
+    }), {
+        maxAttempts: Number.MAX_SAFE_INTEGER,
+        backoff: new ExponentialBackoff({
+            initialDelay: opts.pollIntervalMs ?? 500,
+            maxDelay: opts.maxPollIntervalMs ?? 5000,
+        }),
+    });
+    return opts.timeoutMs
+        ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)
+        : retryPolicy;
+}
+async function compileStrategy(source, policy, opts) {
+    const { data, error } = await postStrategy({
+        body: source,
+        headers: { 'X-Compile-Async': true },
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (error)
+        throw new QTSStrategyCompileError('Strategy submission failed', error);
+    if (!data)
+        throw new QTSStrategyCompileError('Empty response from strategy endpoint');
+    // Sync mode returns { strategyId }; async mode returns { jobId }.
+    if ('strategyId' in data && data.strategyId) {
+        return data.strategyId;
+    }
+    if (!('jobId' in data) || !data.jobId) {
+        throw new QTSStrategyCompileError('Missing jobId/strategyId in compile response');
+    }
+    const compileJobId = data.jobId;
+    const status = await runStage(policy, opts, async ({ signal }) => {
+        const res = await getStrategyStatus({ path: { strategyId: compileJobId }, signal });
+        if (res.error)
+            throw new QTSStrategyCompileError('Compile status request failed', res.error);
+        if (!res.data)
+            throw new QTSStrategyCompileError('Empty compile status response');
+        return res.data;
+    });
+    if (status.status === 'Failed') {
+        throw new QTSStrategyCompileError(status.statusDetail ?? 'Strategy compilation failed');
+    }
+    if (status.status === 'Aborted') {
+        throw new QTSCanceledError('Strategy compilation aborted');
+    }
+    if (!status.strategyId) {
+        throw new QTSStrategyCompileError('Compile completed without a strategyId');
+    }
+    return status.strategyId;
+}
+async function prepareData(req, policy, opts) {
+    const { data, error } = await prepareBacktesting({
+        path: { exchangeId: req.exchangeId, type: TICKER },
+        body: { instrument: req.instrument, from: req.from, to: req.to },
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (error)
+        throw new QTSPreparationError('Prepare submission failed', error);
+    if (!data?.jobId)
+        throw new QTSPreparationError('Missing jobId in prepare response');
+    const prepareJobId = data.jobId;
+    const state = await runStage(policy, opts, async ({ signal }) => {
+        const res = await getPreparationStatus({
+            path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },
+            signal,
+        });
+        if (res.error)
+            throw new QTSPreparationError('Preparation status request failed', res.error);
+        if (!res.data)
+            throw new QTSPreparationError('Empty preparation status response');
+        return res.data;
+    }, (r) => {
+        if (r.size > 0) {
+            opts.onProgress?.({ stage: 'preparing', percent: (r.completed / r.size) * 100 });
+        }
+    });
+    if (state.status === 'Failed') {
+        throw new QTSPreparationError(state.statusDetail ?? 'Data preparation failed');
+    }
+    if (state.status === 'Aborted') {
+        throw new QTSCanceledError('Data preparation aborted');
+    }
+    return prepareJobId;
+}
+async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
+    const { data, error } = await executeBacktesting({
+        path: { exchangeId: req.exchangeId, type: TICKER },
+        body: {
+            prepareJobId,
+            strategyId,
+            ...(req.storeSignals !== undefined ? { storeSignals: req.storeSignals } : {}),
+        },
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (error)
+        throw new QTSExecutionError('Execute submission failed', error);
+    if (!data?.jobId)
+        throw new QTSExecutionError('Missing jobId in execute response');
+    const executeJobId = data.jobId;
+    try {
+        const finalResult = await runStage(policy, opts, async ({ signal }) => {
+            const res = await getExecutionResult({
+                path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
+                signal,
+            });
+            if (res.error)
+                throw new QTSExecutionError('Execution result request failed', res.error);
+            if (!res.data)
+                throw new QTSExecutionError('Empty execution result response');
+            return { ...res.data.state, __result: res.data.results };
+        }, (r) => {
+            if (r.size > 0) {
+                opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });
+            }
+        });
+        if (finalResult.status === 'Failed') {
+            throw new QTSExecutionError(finalResult.statusDetail ?? 'Execution failed');
+        }
+        if (finalResult.status === 'Aborted') {
+            throw new QTSCanceledError('Execution aborted');
+        }
+        return finalResult.__result;
+    }
+    catch (err) {
+        if (err instanceof QTSCanceledError) {
+            await cancelExecution({
+                path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
+            }).catch(() => undefined);
+        }
+        throw err;
+    }
+}
+async function runStage(policy, opts, fetchFn, onEachAttempt) {
+    try {
+        return await policy.execute(async (ctx) => {
+            const result = await fetchFn(ctx);
+            onEachAttempt?.(result);
+            return result;
+        }, opts.signal);
+    }
+    catch (err) {
+        if (err instanceof TaskCancelledError) {
+            if (opts.signal?.aborted)
+                throw new QTSCanceledError('Workflow aborted', err);
+            throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=backtest.js.map

package/dist/workflows/backtest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backtest.js","sourceRoot":"","sources":["../../src/workflows/backtest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAGnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,KAAK,EACL,OAAO,EACP,IAAI,GAGL,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GAChB,MAAM,WAAW,CAAC;AAwCnB,MAAM,MAAM,GAAmB,QAAQ,CAAC;AAIxC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAoB,EACpB,OAAwB,EAAE;IAE1B,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEtC,mCAAmC;IACnC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAErE,kBAAkB;IAClB,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAE1D,aAAa;IACb,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1C,OAAO,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAqB;IAC7C,MAAM,WAAW,GAAG,KAAK,CACvB,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE;QACrB,MAAM,MAAM,GAAI,CAAwC,EAAE,MAAM,CAAC;QACjE,OAAO,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,SAAS,CAAC;IAClD,CAAC,CAAC,EACF;QACE,WAAW,EAAE,MAAM,CAAC,gBAAgB;QACpC,OAAO,EAAE,IAAI,kBAAkB,CAAC;YAC9B,YAAY,EAAE,IAAI,CAAC,cAAc,IAAI,GAAG;YACxC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,IAAI,IAAI;SACzC,CAAC;KACH,CACF,CAAC;IAEF,OAAO,IAAI,CAAC,SAAS;QACnB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;QACzE,CAAC,CAAC,WAAW,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,MAAc,EACd,MAA4C,EAC5C,IAAqB;IAErB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC;QACzC,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE;QACpC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IACH,IAAI,KAAK;QAAE,MAAM,IAAI,uBAAuB,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;IAClF,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,uBAAuB,CAAC,uCAAuC,CAAC,CAAC;IAEtF,kEAAkE;IAClE,IAAI,YAAY,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,uBAAuB,CAAC,8CAA8C,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,MAAM,EACN,IAAI,EACJ,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QACnB,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACpF,IAAI,GAAG,CAAC,KAAK;YAAE,MAAM,IAAI,uBAAuB,CAAC,+BAA+B,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7F,IAAI,CAAC,GAAG,CAAC,IAAI;YAAE,MAAM,IAAI,uBAAuB,CAAC,+BAA+B,CAAC,CAAC;QAClF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC,CACF,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,YAAY,IAAI,6BAA6B,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,gBAAgB,CAAC,8BAA8B,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,uBAAuB,CAAC,wCAAwC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,MAAM,CAAC,UAAU,CAAC;AAC3B,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,GAAoB,EACpB,MAA4C,EAC5C,IAAqB;IAErB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,kBAAkB,CAAC;QAC/C,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE;QAClD,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE;QAChE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IACH,IAAI,KAAK;QAAE,MAAM,IAAI,mBAAmB,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;IAC7E,IAAI,CAAC,IAAI,EAAE,KAAK;QAAE,MAAM,IAAI,mBAAmB,CAAC,mCAAmC,CAAC,CAAC;IAErF,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAC1B,MAAM,EACN,IAAI,EACJ,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QACnB,MAAM,GAAG,GAAG,MAAM,oBAAoB,CAAC;YACrC,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE;YACvE,MAAM;SACP,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,KAAK;YAAE,MAAM,IAAI,mBAAmB,CAAC,mCAAmC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7F,IAAI,CAAC,GAAG,CAAC,IAAI;YAAE,MAAM,IAAI,mBAAmB,CAAC,mCAAmC,CAAC,CAAC;QAClF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;QACJ,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC,CACF,CAAC;IAEF,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,YAAY,IAAI,yBAAyB,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,gBAAgB,CAAC,0BAA0B,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,GAAoB,EACpB,YAAoB,EACpB,UAAkB,EAClB,MAA4C,EAC5C,IAAqB;IAErB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,kBAAkB,CAAC;QAC/C,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE;QAClD,IAAI,EAAE;YACJ,YAAY;YACZ,UAAU;YACV,GAAG,CAAC,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9E;QACD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IACH,IAAI,KAAK;QAAE,MAAM,IAAI,iBAAiB,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;IAC3E,IAAI,CAAC,IAAI,EAAE,KAAK;QAAE,MAAM,IAAI,iBAAiB,CAAC,mCAAmC,CAAC,CAAC;IAEnF,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,QAAQ,CAChC,MAAM,EACN,IAAI,EACJ,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;YACnB,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC;gBACnC,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE;gBACvE,MAAM;aACP,CAAC,CAAC;YACH,IAAI,GAAG,CAAC,KAAK;gBAAE,MAAM,IAAI,iBAAiB,CAAC,iCAAiC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YACzF,IAAI,CAAC,GAAG,CAAC,IAAI;gBAAE,MAAM,IAAI,iBAAiB,CAAC,iCAAiC,CAAC,CAAC;YAC9E,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3D,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;YACJ,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;YACnF,CAAC;QACH,CAAC,CACF,CAAC;QAEF,IAAI,WAAW,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,iBAAiB,CAAC,WAAW,CAAC,YAAY,IAAI,kBAAkB,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,WAAW,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;YACpC,MAAM,eAAe,CAAC;gBACpB,IAAI,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE;aACxE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,MAA4C,EAC5C,IAAqB,EACrB,OAAkD,EAClD,aAA8B;IAE9B,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;YAC9E,MAAM,IAAI,eAAe,CAAC,kBAAkB,IAAI,CAAC,SAAS,IAAI,EAAE,GAAG,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@qtsurfer/sdk",
+  "version": "0.1.0",
+  "description": "Opinionated TypeScript SDK for QTSurfer: workflow orchestration, domain objects, normalized errors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QTSurfer/sdk-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/QTSurfer/sdk-ts/issues"
+  },
+  "homepage": "https://github.com/QTSurfer/sdk-ts#readme",
+  "author": "QTSurfer (https://github.com/QTSurfer)",
+  "license": "Apache-2.0",
+  "keywords": [
+    "qtsurfer",
+    "sdk",
+    "typescript",
+    "backtesting",
+    "trading",
+    "workflow"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@qtsurfer/api-client": "^0.1.0",
+    "cockatiel": "^3.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/client.ts

@@ -0,0 +1,34 @@
+import { client as apiClient } from '@qtsurfer/api-client';
+import {
+  backtest,
+  type BacktestOptions,
+  type BacktestRequest,
+  type BacktestResult,
+} from './workflows/backtest';
+
+export interface QTSurferOptions {
+  baseUrl: string;
+  token?: string;
+  fetch?: typeof fetch;
+}
+
+export class QTSurfer {
+  constructor(options: QTSurferOptions) {
+    apiClient.setConfig({
+      baseUrl: options.baseUrl,
+      ...(options.token
+        ? { headers: { Authorization: `Bearer ${options.token}` } }
+        : {}),
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+  }
+
+  backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult> {
+    return backtest(req, opts);
+  }
+
+  // Future surface:
+  //   strategies: { compile, status, list }
+  //   instruments: { list, get } with TTL cache
+  //   jobs: { cancel, stream, result }
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class QTSError extends Error {
+  constructor(message: string, readonly cause?: unknown) {
+    super(message);
+    this.name = 'QTSError';
+  }
+}
+
+export class QTSStrategyCompileError extends QTSError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QTSStrategyCompileError';
+  }
+}
+
+export class QTSPreparationError extends QTSError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QTSPreparationError';
+  }
+}
+
+export class QTSExecutionError extends QTSError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QTSExecutionError';
+  }
+}
+
+export class QTSTimeoutError extends QTSError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QTSTimeoutError';
+  }
+}
+
+export class QTSCanceledError extends QTSError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = 'QTSCanceledError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { QTSurfer, type QTSurferOptions } from './client';
+export {
+  QTSError,
+  QTSStrategyCompileError,
+  QTSPreparationError,
+  QTSExecutionError,
+  QTSTimeoutError,
+  QTSCanceledError,
+} from './errors';
+export type {
+  BacktestRequest,
+  BacktestResult,
+  BacktestProgress,
+  BacktestStage,
+  BacktestOptions,
+} from './workflows/backtest';

package/src/workflows/backtest.ts

@@ -0,0 +1,276 @@
+import {
+  cancelExecution,
+  executeBacktesting,
+  getExecutionResult,
+  getPreparationStatus,
+  getStrategyStatus,
+  postStrategy,
+  prepareBacktesting,
+  type DataSourceType,
+  type ResultMap,
+} from '@qtsurfer/api-client';
+import {
+  ExponentialBackoff,
+  TaskCancelledError,
+  TimeoutStrategy,
+  handleWhenResult,
+  retry,
+  timeout,
+  wrap,
+  type IPolicy,
+  type ICancellationContext,
+} from 'cockatiel';
+import {
+  QTSCanceledError,
+  QTSExecutionError,
+  QTSPreparationError,
+  QTSStrategyCompileError,
+  QTSTimeoutError,
+} from '../errors';
+
+export interface BacktestRequest {
+  /** Strategy source code (Java) */
+  strategy: string;
+  /** Exchange id, e.g. `binance` */
+  exchangeId: string;
+  /** Instrument symbol, e.g. `BTCUSDT` */
+  instrument: string;
+  /** Date range start (ISO-8601, ISO DATE or BASIC ISO DATE) */
+  from: string;
+  /** Date range end (same formats as `from`) */
+  to: string;
+  /** When true, the worker uploads emitted signals to object storage. */
+  storeSignals?: boolean;
+}
+
+export type BacktestResult = ResultMap;
+
+export type BacktestStage = 'compiling' | 'preparing' | 'executing';
+
+export interface BacktestProgress {
+  stage: BacktestStage;
+  /** 0-100 when size is known. Undefined during stage start. */
+  percent?: number;
+}
+
+export interface BacktestOptions {
+  /** Abort the workflow. Cancels the current poll and calls `cancelExecution` server-side if execution has started. */
+  signal?: AbortSignal;
+  /** Called on stage transitions and after each poll with updated progress. */
+  onProgress?: (p: BacktestProgress) => void;
+  /** Initial interval between polls. Default 500ms, backed off up to `maxPollIntervalMs`. */
+  pollIntervalMs?: number;
+  /** Upper bound for exponential backoff. Default 5000ms. */
+  maxPollIntervalMs?: number;
+  /** Per-stage timeout. Default none. */
+  timeoutMs?: number;
+}
+
+const TICKER: DataSourceType = 'ticker';
+
+type JobStatus = 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
+
+export async function backtest(
+  req: BacktestRequest,
+  opts: BacktestOptions = {},
+): Promise<BacktestResult> {
+  const policy = buildStagePolicy(opts);
+
+  // 1. Compile strategy (async mode)
+  opts.onProgress?.({ stage: 'compiling' });
+  const strategyId = await compileStrategy(req.strategy, policy, opts);
+
+  // 2. Prepare data
+  opts.onProgress?.({ stage: 'preparing' });
+  const prepareJobId = await prepareData(req, policy, opts);
+
+  // 3. Execute
+  opts.onProgress?.({ stage: 'executing' });
+  return executeStrategy(req, prepareJobId, strategyId, policy, opts);
+}
+
+function buildStagePolicy(opts: BacktestOptions): IPolicy<ICancellationContext, never> {
+  const retryPolicy = retry(
+    handleWhenResult((r) => {
+      const status = (r as { status?: JobStatus } | undefined)?.status;
+      return status === 'New' || status === 'Started';
+    }),
+    {
+      maxAttempts: Number.MAX_SAFE_INTEGER,
+      backoff: new ExponentialBackoff({
+        initialDelay: opts.pollIntervalMs ?? 500,
+        maxDelay: opts.maxPollIntervalMs ?? 5000,
+      }),
+    },
+  );
+
+  return opts.timeoutMs
+    ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy)
+    : retryPolicy;
+}
+
+async function compileStrategy(
+  source: string,
+  policy: IPolicy<ICancellationContext, never>,
+  opts: BacktestOptions,
+): Promise<string> {
+  const { data, error } = await postStrategy({
+    body: source,
+    headers: { 'X-Compile-Async': true },
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  if (error) throw new QTSStrategyCompileError('Strategy submission failed', error);
+  if (!data) throw new QTSStrategyCompileError('Empty response from strategy endpoint');
+
+  // Sync mode returns { strategyId }; async mode returns { jobId }.
+  if ('strategyId' in data && data.strategyId) {
+    return data.strategyId;
+  }
+  if (!('jobId' in data) || !data.jobId) {
+    throw new QTSStrategyCompileError('Missing jobId/strategyId in compile response');
+  }
+
+  const compileJobId = data.jobId;
+  const status = await runStage(
+    policy,
+    opts,
+    async ({ signal }) => {
+      const res = await getStrategyStatus({ path: { strategyId: compileJobId }, signal });
+      if (res.error) throw new QTSStrategyCompileError('Compile status request failed', res.error);
+      if (!res.data) throw new QTSStrategyCompileError('Empty compile status response');
+      return res.data;
+    },
+  );
+
+  if (status.status === 'Failed') {
+    throw new QTSStrategyCompileError(status.statusDetail ?? 'Strategy compilation failed');
+  }
+  if (status.status === 'Aborted') {
+    throw new QTSCanceledError('Strategy compilation aborted');
+  }
+  if (!status.strategyId) {
+    throw new QTSStrategyCompileError('Compile completed without a strategyId');
+  }
+  return status.strategyId;
+}
+
+async function prepareData(
+  req: BacktestRequest,
+  policy: IPolicy<ICancellationContext, never>,
+  opts: BacktestOptions,
+): Promise<string> {
+  const { data, error } = await prepareBacktesting({
+    path: { exchangeId: req.exchangeId, type: TICKER },
+    body: { instrument: req.instrument, from: req.from, to: req.to },
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  if (error) throw new QTSPreparationError('Prepare submission failed', error);
+  if (!data?.jobId) throw new QTSPreparationError('Missing jobId in prepare response');
+
+  const prepareJobId = data.jobId;
+  const state = await runStage(
+    policy,
+    opts,
+    async ({ signal }) => {
+      const res = await getPreparationStatus({
+        path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },
+        signal,
+      });
+      if (res.error) throw new QTSPreparationError('Preparation status request failed', res.error);
+      if (!res.data) throw new QTSPreparationError('Empty preparation status response');
+      return res.data;
+    },
+    (r) => {
+      if (r.size > 0) {
+        opts.onProgress?.({ stage: 'preparing', percent: (r.completed / r.size) * 100 });
+      }
+    },
+  );
+
+  if (state.status === 'Failed') {
+    throw new QTSPreparationError(state.statusDetail ?? 'Data preparation failed');
+  }
+  if (state.status === 'Aborted') {
+    throw new QTSCanceledError('Data preparation aborted');
+  }
+  return prepareJobId;
+}
+
+async function executeStrategy(
+  req: BacktestRequest,
+  prepareJobId: string,
+  strategyId: string,
+  policy: IPolicy<ICancellationContext, never>,
+  opts: BacktestOptions,
+): Promise<BacktestResult> {
+  const { data, error } = await executeBacktesting({
+    path: { exchangeId: req.exchangeId, type: TICKER },
+    body: {
+      prepareJobId,
+      strategyId,
+      ...(req.storeSignals !== undefined ? { storeSignals: req.storeSignals } : {}),
+    },
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  if (error) throw new QTSExecutionError('Execute submission failed', error);
+  if (!data?.jobId) throw new QTSExecutionError('Missing jobId in execute response');
+
+  const executeJobId = data.jobId;
+
+  try {
+    const finalResult = await runStage(
+      policy,
+      opts,
+      async ({ signal }) => {
+        const res = await getExecutionResult({
+          path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
+          signal,
+        });
+        if (res.error) throw new QTSExecutionError('Execution result request failed', res.error);
+        if (!res.data) throw new QTSExecutionError('Empty execution result response');
+        return { ...res.data.state, __result: res.data.results };
+      },
+      (r) => {
+        if (r.size > 0) {
+          opts.onProgress?.({ stage: 'executing', percent: (r.completed / r.size) * 100 });
+        }
+      },
+    );
+
+    if (finalResult.status === 'Failed') {
+      throw new QTSExecutionError(finalResult.statusDetail ?? 'Execution failed');
+    }
+    if (finalResult.status === 'Aborted') {
+      throw new QTSCanceledError('Execution aborted');
+    }
+    return finalResult.__result;
+  } catch (err) {
+    if (err instanceof QTSCanceledError) {
+      await cancelExecution({
+        path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
+      }).catch(() => undefined);
+    }
+    throw err;
+  }
+}
+
+async function runStage<T extends { status: JobStatus }>(
+  policy: IPolicy<ICancellationContext, never>,
+  opts: BacktestOptions,
+  fetchFn: (ctx: ICancellationContext) => Promise<T>,
+  onEachAttempt?: (r: T) => void,
+): Promise<T> {
+  try {
+    return await policy.execute(async (ctx) => {
+      const result = await fetchFn(ctx);
+      onEachAttempt?.(result);
+      return result;
+    }, opts.signal);
+  } catch (err) {
+    if (err instanceof TaskCancelledError) {
+      if (opts.signal?.aborted) throw new QTSCanceledError('Workflow aborted', err);
+      throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);
+    }
+    throw err;
+  }
+}