feat: v0.2 domain objects (Strategy, Backtest) + remove internal URLs

Domain objects:
- Strategy: compiled handle returned by QTSurfer.compile(), reusable across backtests
- Backtest (was BacktestJob): running execution handle with id(), state(), progress() (Flow.Publisher), await(), cancel()
- BacktestWorkflow (internal): renamed from Backtest to avoid clash with the new public Backtest class
- QTSurfer.backtest() shortcut reimplemented as compile().thenCompose(backtest).thenCompose(await)

Security:
- Remove hardcoded staging URL (api.qtsurfer.net) from integration test default
- QTSURFER_API_URL now required alongside JWT_API_TOKEN; test skips when either is absent
- Javadoc and README examples use the official domain (api.qtsurfer.com) as illustration only

Tests:
- DomainObjectsTest: compile handle, backtest+await, progress publisher, cancel with server-side cancelExecution, runFull shortcut
- Legacy cancel test disabled (cancellation is on Backtest handle, not on the runFull shortcut future)

Author: mrmx

README.md

@@ -63,7 +63,7 @@ import java.time.Duration;
 import java.util.concurrent.CompletableFuture;
 
 QTSurfer qts = QTSurfer.builder()
-        .baseUrl("https://api.qtsurfer.net/v1")
+        .baseUrl("https://api.qtsurfer.com/v1")
         .token(System.getenv("JWT_API_TOKEN"))
         .build();
 
@@ -154,12 +154,12 @@ future.cancel(true);
 
 Hits the real backend with `ForcedTradeStrategy` on `binance BTC/USDT` for the previous UTC day. Controlled by env vars:
 
-- `JWT_API_TOKEN` — required; without it the test is disabled via `@EnabledIfEnvironmentVariable`.
-- `QTSURFER_API_URL` — optional; defaults to `https://api.qtsurfer.net/v1` (Preproduction).
-- `QTSURFER_TEST_VERBOSE=1` — stream progress events and the final result through SLF4J.
+- `JWT_API_TOKEN` — required; the test is skipped when absent.
+- `QTSURFER_API_URL` — required; the test is skipped when absent.
+- `QTSURFER_TEST_VERBOSE=1` — optional; stream progress events and the final result through SLF4J.
 
 ```bash
-JWT_API_TOKEN=... QTSURFER_TEST_VERBOSE=1 mvn -B -Dtest='*IntegrationTest' test
+JWT_API_TOKEN=... QTSURFER_API_URL=... QTSURFER_TEST_VERBOSE=1 mvn -B -Dtest='*IntegrationTest' test
 ```
 
 ## Roadmap

src/main/java/net/qtsurfer/api/sdk/Backtest.java

@@ -0,0 +1,79 @@
+package net.qtsurfer.api.sdk;
+
+import net.qtsurfer.api.client.model.ResultMap;
+
+import java.util.Objects;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Flow;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Handle for a running backtest execution. Returned by {@link Strategy#backtest}
+ * once the execute request has been accepted by the backend.
+ *
+ * <ul>
+ *   <li>{@link #await()} resolves with the final {@link ResultMap} when polling completes.</li>
+ *   <li>{@link #progress()} streams {@link BacktestProgress} events through a {@link Flow.Publisher}.</li>
+ *   <li>{@link #cancel()} triggers a best-effort server-side {@code cancelExecution}.</li>
+ *   <li>{@link #state()} returns a local snapshot of the lifecycle.</li>
+ * </ul>
+ */
+public final class Backtest {
+
+    /** Execution lifecycle as observed by the SDK. */
+    public enum State { EXECUTING, COMPLETED, FAILED, CANCELED }
+
+    private final String id;
+    private final Strategy strategy;
+    private final CompletableFuture<ResultMap> result;
+    private final Flow.Publisher<BacktestProgress> progress;
+    private final AtomicReference<State> state;
+    private final Runnable cancelHook;
+
+    public Backtest(
+            String id,
+            Strategy strategy,
+            CompletableFuture<ResultMap> result,
+            Flow.Publisher<BacktestProgress> progress,
+            AtomicReference<State> state,
+            Runnable cancelHook) {
+        this.id = Objects.requireNonNull(id, "id");
+        this.strategy = Objects.requireNonNull(strategy, "strategy");
+        this.result = Objects.requireNonNull(result, "result");
+        this.progress = Objects.requireNonNull(progress, "progress");
+        this.state = Objects.requireNonNull(state, "state");
+        this.cancelHook = Objects.requireNonNull(cancelHook, "cancelHook");
+    }
+
+    /** Server-side execute jobId. */
+    public String id() { return id; }
+
+    public Strategy strategy() { return strategy; }
+
+    public State state() { return state.get(); }
+
+    /** Reactive-streams feed of progress events; terminates when the job reaches a terminal state. */
+    public Flow.Publisher<BacktestProgress> progress() { return progress; }
+
+    /** Resolves with the final ResultMap. Completes exceptionally on failure or cancellation. */
+    public CompletableFuture<ResultMap> await() { return result; }
+
+    /**
+     * Request cancellation. Cancels the underlying polling future and best-effort
+     * calls {@code cancelExecution} server-side.
+     *
+     * @return {@code true} if the call caused a transition from {@link State#EXECUTING}
+     */
+    public boolean cancel() {
+        if (!state.compareAndSet(State.EXECUTING, State.CANCELED)) {
+            return false;
+        }
+        cancelHook.run();
+        return true;
+    }
+
+    @Override
+    public String toString() {
+        return "Backtest[" + id + ", state=" + state.get() + "]";
+    }
+}

src/main/java/net/qtsurfer/api/sdk/QTSurfer.java

@@ -4,7 +4,7 @@
 import net.qtsurfer.api.client.invoker.ApiClient;
 import net.qtsurfer.api.client.model.ResultMap;
 import net.qtsurfer.api.sdk.internal.HttpStrategyCompileClient;
-import net.qtsurfer.api.sdk.workflows.Backtest;
+import net.qtsurfer.api.sdk.workflows.BacktestWorkflow;
 
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
@@ -17,57 +17,69 @@
  * <h2>Quick start</h2>
  * <pre>{@code
  * QTSurfer qts = QTSurfer.builder()
- *     .baseUrl("https://api.qtsurfer.net/v1")
+ *     .baseUrl("https://api.qtsurfer.com/v1")
  *     .token(System.getenv("JWT_API_TOKEN"))
  *     .build();
  *
- * CompletableFuture<ResultMap> future = qts.backtest(
- *     BacktestRequest.builder()
- *         .strategy(Files.readString(Path.of("Strategy.java")))
- *         .exchangeId("binance")
- *         .instrument("BTC/USDT")
- *         .from("2026-04-13T00:00:00Z")
- *         .to("2026-04-14T00:00:00Z")
- *         .build(),
- *     BacktestOptions.builder()
- *         .onProgress(p -> System.out.println(p.stage() + " " + p.percent()))
- *         .timeout(Duration.ofMinutes(10))
- *         .build());
+ * // One-shot shortcut:
+ * ResultMap result = qts.backtest(request, options).join();
  *
- * ResultMap result = future.join();
+ * // Or decomposed for streaming / reuse:
+ * Strategy strategy = qts.compile(source).join();
+ * Backtest job = strategy.backtest(request, options).join();
+ * job.progress().subscribe( ... );
+ * ResultMap result = job.await().join();
  * }</pre>
  */
 public final class QTSurfer {
 
     private final QTSurferOptions options;
-    private final Backtest backtestWorkflow;
+    private final BacktestWorkflow backtestWorkflow;
 
-    private QTSurfer(QTSurferOptions options, Backtest backtestWorkflow) {
+    private QTSurfer(QTSurferOptions options, BacktestWorkflow backtestWorkflow) {
         this.options = options;
         this.backtestWorkflow = backtestWorkflow;
     }
 
     public QTSurferOptions options() { return options; }
 
+    /** Compile a strategy source. Resolves with a {@link Strategy} handle you can reuse. */
+    public CompletableFuture<Strategy> compile(String source) {
+        return compile(source, BacktestOptions.defaults());
+    }
+
+    public CompletableFuture<Strategy> compile(String source, BacktestOptions options) {
+        Objects.requireNonNull(source, "source");
+        return backtestWorkflow.compile(source, options);
+    }
+
+    /** Convenience: compile the strategy embedded in the given request. */
+    public CompletableFuture<Strategy> compile(BacktestRequest request) {
+        Objects.requireNonNull(request, "request");
+        return compile(request.strategy(), BacktestOptions.defaults());
+    }
+
+    public CompletableFuture<Strategy> compile(BacktestRequest request, BacktestOptions options) {
+        Objects.requireNonNull(request, "request");
+        return compile(request.strategy(), options);
+    }
+
     /**
-     * Run a backtest (compile → prepare → execute) returning a {@link CompletableFuture} that
-     * resolves with the result {@link ResultMap} when the whole workflow completes.
-     *
-     * <p>Cancel the returned future to stop polling and trigger a best-effort server-side
-     * {@code cancelExecution} if the workflow already reached the execute stage.
+     * Run the full compile → prepare → execute → await pipeline as a single future.
+     * Equivalent to
+     * {@code compile(request).thenCompose(s -> s.backtest(request, options)).thenCompose(Backtest::await)}.
      */
     public CompletableFuture<ResultMap> backtest(BacktestRequest request) {
         return backtest(request, BacktestOptions.defaults());
     }
 
     public CompletableFuture<ResultMap> backtest(BacktestRequest request, BacktestOptions options) {
         Objects.requireNonNull(request, "request");
-        return backtestWorkflow.run(request, options);
+        return backtestWorkflow.runFull(request, options);
     }
 
     public static Builder builder() { return new Builder(); }
 
-    /** Fluent builder mirroring {@link QTSurferOptions}. */
     public static final class Builder {
         private final QTSurferOptions.Builder delegate = QTSurferOptions.builder();
 
@@ -85,13 +97,9 @@ public QTSurfer build() {
                 String bearer = "Bearer " + opts.token();
                 apiClient.setRequestInterceptor(b -> b.header("Authorization", bearer));
             }
-            if (opts.httpClient() != null) {
-                apiClient.setHttpClientBuilder(java.net.http.HttpClient.newBuilder()
-                        .connectTimeout(java.time.Duration.ofSeconds(30))); // fallback; api-client requires a builder
-            }
             BacktestingApi backtestingApi = new BacktestingApi(apiClient);
             ExecutorService exec = opts.executor() != null ? opts.executor() : ForkJoinPool.commonPool();
-            return new QTSurfer(opts, new Backtest(
+            return new QTSurfer(opts, new BacktestWorkflow(
                     new HttpStrategyCompileClient(apiClient), backtestingApi, exec));
         }
     }

src/main/java/net/qtsurfer/api/sdk/QTSurferOptions.java

@@ -8,7 +8,7 @@
 /**
  * Configuration for a {@link QTSurfer} client.
  *
- * @param baseUrl    API base URL (e.g. {@code https://api.qtsurfer.net/v1})
+ * @param baseUrl    API base URL (e.g. {@code https://api.qtsurfer.com/v1})
  * @param token      bearer token; {@code null} disables the {@code Authorization} header
  * @param httpClient optional custom {@link HttpClient}; when {@code null} the SDK creates one
  * @param executor   executor that runs the async workflow; when {@code null} uses {@code ForkJoinPool.commonPool()}

src/main/java/net/qtsurfer/api/sdk/Strategy.java

@@ -0,0 +1,42 @@
+package net.qtsurfer.api.sdk;
+
+import net.qtsurfer.api.sdk.workflows.BacktestWorkflow;
+
+import java.util.Objects;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * A compiled strategy handle returned by {@link QTSurfer#compile}. Use it to
+ * spawn one or more {@link Backtest}s that reuse the same compilation.
+ */
+public final class Strategy {
+
+    private final String id;
+    private final BacktestWorkflow workflow;
+
+    /** Internal constructor used by the SDK workflow; not part of the public contract. */
+    public Strategy(String id, BacktestWorkflow workflow) {
+        this.id = Objects.requireNonNull(id, "id");
+        this.workflow = Objects.requireNonNull(workflow, "workflow");
+    }
+
+    /** The compiled strategyId as returned by the backend. */
+    public String id() {
+        return id;
+    }
+
+    /** Run a backtest with this strategy. Prepare + execute start immediately. */
+    public CompletableFuture<Backtest> backtest(BacktestRequest request, BacktestOptions options) {
+        Objects.requireNonNull(request, "request");
+        return workflow.submitExecution(this, request, options != null ? options : BacktestOptions.defaults());
+    }
+
+    public CompletableFuture<Backtest> backtest(BacktestRequest request) {
+        return backtest(request, BacktestOptions.defaults());
+    }
+
+    @Override
+    public String toString() {
+        return "Strategy[" + id + "]";
+    }
+}