feat: hourly tickers/klines downloads as Lastra/Parquet streams (0.2.0)

Two new SDK methods that wrap the binary endpoints introduced in
net.qtsurfer:api-client v0.1.2:

  QTSurfer#tickers(exchangeId, base, quote, hour[, format]) -> InputStream
  QTSurfer#klines (exchangeId, base, quote, hour[, format]) -> InputStream

The default wire format is Lastra (application/vnd.lastra) which streams
the raw QTSurfer columnar bytes; pass DownloadFormat.PARQUET for
on-the-fly Parquet conversion server-side. The returned InputStream is
caller-owned (use try-with-resources / Files.copy / a Lastra reader).

HTTP errors surface as QTSDownloadError, a new subclass of QTSError.
Both methods are unit-tested against an in-process com.sun.net.httpserver
(URL building, format query param, bearer auth header, error mapping to
QTSDownloadError).

Bump api-client dependency to v0.1.2 (ExchangeBinaryDownloads).

This release also formalizes the v0.2 domain-objects work that was
already on main but never tagged: Strategy/Backtest handles plus the
removal of internal staging URLs from the integration test default.
See CHANGELOG.md for the consolidated entry.

Author: mrmx

CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-05-01
+
+### Added
+
+- **Domain objects (`Strategy`, `Backtest`):**
+  - `QTSurfer#compile(...)` returns a reusable `Strategy` handle that can launch multiple backtests.
+  - `Strategy#backtest(...)` returns a `Backtest` handle exposing `id()`, `state()`, `progress()` (a `Flow.Publisher<BacktestProgress>`), `await()`, and `cancel()`.
+  - `QTSurfer#backtest(request, options)` shortcut now composes `compile → backtest → await` over the new objects.
+- **Hourly tickers/klines downloads:**
+  - `QTSurfer#tickers(exchangeId, base, quote, hour[, format])` and `QTSurfer#klines(...)` — stream one hour of raw tickers or klines as `InputStream`.
+  - `DownloadFormat` enum (`LASTRA` default, `PARQUET` for on-the-fly conversion).
+  - `QTSDownloadError` (subclass of `QTSError`) — surfaced when the download fails (HTTP 4xx/5xx, transport error).
+
+### Changed
+
+- `api-client` dependency bumped to `v0.1.2` (adds `ExchangeBinaryDownloads`).
+- Internal `Backtest` workflow class renamed to `BacktestWorkflow` to free the public `Backtest` name for the new domain handle.
+
+### Removed
+
+- Hardcoded staging URL from the integration test default; `QTSURFER_API_URL` is now required alongside `JWT_API_TOKEN` (the test skips when either is absent).
+- Javadoc and README examples use the public domain (`api.qtsurfer.com`) instead of internal/staging URLs.
+
 ## [0.1.0] — 2026-04-15
 
 ### Added

README.md

@@ -106,6 +106,28 @@ Progress is emitted:
 - On every stage transition (`percent == null`).
 - After each poll where the backend reports `size > 0` (`percent` in 0–100).
 
+## Hourly tickers/klines downloads
+
+Stream one hour of raw ticker or kline data for an instrument. The default wire format is
+[Lastra](https://github.com/QTSurfer/lastra-java) (`application/vnd.lastra`); pass
+`DownloadFormat.PARQUET` for on-the-fly Parquet conversion.
+
+```java
+import net.qtsurfer.api.sdk.DownloadFormat;
+
+// Lastra (default), streamed straight to disk
+try (var in = qts.tickers("binance", "BTC", "USDT", "2026-01-15T10")) {
+    Files.copy(in, Path.of("BTC_USDT_2026-01-15_h10.lastra"));
+}
+
+// Parquet
+try (var in = qts.klines("binance", "BTC", "USDT", "2026-01-15T10", DownloadFormat.PARQUET)) {
+    // feed into Apache Parquet, DuckDB, etc.
+}
+```
+
+The caller closes the stream. HTTP errors surface as `QTSDownloadError` (subclass of `QTSError`).
+
 ## Error hierarchy
 
 All SDK errors extend `QTSError` (a `RuntimeException`) and surface as the cause of the `CompletionException` wrapping them when the future fails.
@@ -119,6 +141,7 @@ try {
         case QTSStrategyCompileError x -> log.error("Compile failed: {}", x.getMessage());
         case QTSPreparationError x     -> log.error("Data prep failed: {}", x.getMessage());
         case QTSExecutionError x       -> log.error("Execution failed: {}", x.getMessage());
+        case QTSDownloadError x        -> log.error("Download failed: {}", x.getMessage());
         case QTSTimeoutError x         -> log.error("Stage timed out: {}", x.getMessage());
         case QTSCanceledError x        -> log.error("Canceled");
         default                        -> throw e;

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>net.qtsurfer</groupId>
     <artifactId>sdk</artifactId>
-    <version>0.1.0</version>
+    <version>0.2.0</version>
     <packaging>jar</packaging>
 
     <name>QTSurfer SDK</name>
@@ -48,7 +48,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
 
-        <api.client.version>v0.1.1</api.client.version>
+        <api.client.version>v0.1.2</api.client.version>
         <failsafe.version>3.3.2</failsafe.version>
         <slf4j.version>2.0.16</slf4j.version>
         <jackson.version>2.18.2</jackson.version>

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

@@ -0,0 +1,28 @@
+package net.qtsurfer.api.sdk;
+
+import net.qtsurfer.api.client.binary.ExchangeBinaryDownloads;
+
+/**
+ * Wire format for hourly tickers/klines downloads.
+ *
+ * <ul>
+ *   <li>{@link #LASTRA} — native QTSurfer columnar format ({@code application/vnd.lastra}).
+ *       Cheaper to serve and to consume. Use a Lastra reader (e.g. {@code lastra-java}).</li>
+ *   <li>{@link #PARQUET} — Apache Parquet, converted on-the-fly server-side
+ *       ({@code application/vnd.apache.parquet}). Use when the client can't read Lastra.</li>
+ * </ul>
+ */
+public enum DownloadFormat {
+    LASTRA(ExchangeBinaryDownloads.Format.LASTRA),
+    PARQUET(ExchangeBinaryDownloads.Format.PARQUET);
+
+    private final ExchangeBinaryDownloads.Format wire;
+
+    DownloadFormat(ExchangeBinaryDownloads.Format wire) {
+        this.wire = wire;
+    }
+
+    ExchangeBinaryDownloads.Format wire() {
+        return wire;
+    }
+}

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

@@ -1,11 +1,15 @@
 package net.qtsurfer.api.sdk;
 
 import net.qtsurfer.api.client.api.BacktestingApi;
+import net.qtsurfer.api.client.binary.ExchangeBinaryDownloads;
 import net.qtsurfer.api.client.invoker.ApiClient;
+import net.qtsurfer.api.client.invoker.ApiException;
 import net.qtsurfer.api.client.model.ResultMap;
+import net.qtsurfer.api.sdk.errors.QTSDownloadError;
 import net.qtsurfer.api.sdk.internal.HttpStrategyCompileClient;
 import net.qtsurfer.api.sdk.workflows.BacktestWorkflow;
 
+import java.io.InputStream;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutorService;
@@ -35,10 +39,12 @@ public final class QTSurfer {
 
     private final QTSurferOptions options;
     private final BacktestWorkflow backtestWorkflow;
+    private final ExchangeBinaryDownloads downloads;
 
-    private QTSurfer(QTSurferOptions options, BacktestWorkflow backtestWorkflow) {
+    private QTSurfer(QTSurferOptions options, BacktestWorkflow backtestWorkflow, ExchangeBinaryDownloads downloads) {
         this.options = options;
         this.backtestWorkflow = backtestWorkflow;
+        this.downloads = downloads;
     }
 
     public QTSurferOptions options() { return options; }
@@ -78,6 +84,58 @@ public CompletableFuture<ResultMap> backtest(BacktestRequest request, BacktestOp
         return backtestWorkflow.runFull(request, options);
     }
 
+    /**
+     * Download one hour of raw tickers for an instrument as a streaming
+     * {@link InputStream}. Defaults to {@link DownloadFormat#LASTRA}; pass
+     * {@link DownloadFormat#PARQUET} for on-the-fly Parquet conversion.
+     *
+     * <p>The caller is responsible for closing the stream — typically via
+     * try-with-resources, piping to {@code Files.copy(...)}, or feeding it
+     * into a Lastra/Parquet reader.
+     *
+     * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure
+     */
+    public InputStream tickers(String exchangeId, String base, String quote, String hour) {
+        return tickers(exchangeId, base, quote, hour, DownloadFormat.LASTRA);
+    }
+
+    public InputStream tickers(String exchangeId, String base, String quote, String hour, DownloadFormat format) {
+        Objects.requireNonNull(format, "format");
+        try {
+            return downloads.getTickersHour(exchangeId, base, quote, hour, format.wire());
+        } catch (ApiException e) {
+            throw new QTSDownloadError(
+                    "tickers download failed: " + describe(e), e);
+        }
+    }
+
+    /**
+     * Download one hour of klines for an instrument as a streaming
+     * {@link InputStream}. See {@link #tickers} for semantics.
+     *
+     * @throws QTSDownloadError on HTTP 4xx/5xx or transport failure
+     */
+    public InputStream klines(String exchangeId, String base, String quote, String hour) {
+        return klines(exchangeId, base, quote, hour, DownloadFormat.LASTRA);
+    }
+
+    public InputStream klines(String exchangeId, String base, String quote, String hour, DownloadFormat format) {
+        Objects.requireNonNull(format, "format");
+        try {
+            return downloads.getKlinesHour(exchangeId, base, quote, hour, format.wire());
+        } catch (ApiException e) {
+            throw new QTSDownloadError(
+                    "klines download failed: " + describe(e), e);
+        }
+    }
+
+    private static String describe(ApiException e) {
+        if (e.getResponseBody() != null && !e.getResponseBody().isBlank()) {
+            return "HTTP " + e.getCode() + " — " + e.getResponseBody();
+        }
+        return "HTTP " + e.getCode();
+    }
+
     public static Builder builder() { return new Builder(); }
 
     public static final class Builder {
@@ -99,8 +157,9 @@ public QTSurfer build() {
             }
             BacktestingApi backtestingApi = new BacktestingApi(apiClient);
             ExecutorService exec = opts.executor() != null ? opts.executor() : ForkJoinPool.commonPool();
-            return new QTSurfer(opts, new BacktestWorkflow(
-                    new HttpStrategyCompileClient(apiClient), backtestingApi, exec));
+            BacktestWorkflow workflow = new BacktestWorkflow(
+                    new HttpStrategyCompileClient(apiClient), backtestingApi, exec);
+            return new QTSurfer(opts, workflow, new ExchangeBinaryDownloads(apiClient));
         }
     }
 }

src/main/java/net/qtsurfer/api/sdk/errors/QTSDownloadError.java

@@ -0,0 +1,16 @@
+package net.qtsurfer.api.sdk.errors;
+
+/**
+ * Raised when an hourly tickers/klines download fails — wraps the underlying
+ * {@link net.qtsurfer.api.client.invoker.ApiException} (HTTP 4xx/5xx, transport error).
+ */
+public class QTSDownloadError extends QTSError {
+
+    public QTSDownloadError(String message) {
+        super(message);
+    }
+
+    public QTSDownloadError(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

src/test/java/net/qtsurfer/api/sdk/DownloadsTest.java

@@ -0,0 +1,96 @@
+package net.qtsurfer.api.sdk;
+
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import net.qtsurfer.api.sdk.errors.QTSDownloadError;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class DownloadsTest {
+
+    private HttpServer server;
+    private QTSurfer qts;
+    private final List<HttpExchange> exchanges = new ArrayList<>();
+    private final AtomicReference<byte[]> responseBody = new AtomicReference<>(new byte[0]);
+    private final AtomicReference<Integer> responseStatus = new AtomicReference<>(200);
+
+    @BeforeEach
+    void start() throws IOException {
+        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        server.createContext("/", exchange -> {
+            exchanges.add(exchange);
+            byte[] body = responseBody.get();
+            int status = responseStatus.get();
+            exchange.getResponseHeaders().add("Content-Type", "application/vnd.lastra");
+            exchange.sendResponseHeaders(status, body.length == 0 ? -1 : body.length);
+            try (var os = exchange.getResponseBody()) {
+                if (body.length > 0) os.write(body);
+            }
+        });
+        server.start();
+        qts = QTSurfer.builder()
+                .baseUrl("http://127.0.0.1:" + server.getAddress().getPort())
+                .token("test-token")
+                .build();
+    }
+
+    @AfterEach
+    void stop() {
+        server.stop(0);
+    }
+
+    @Test
+    void tickersDefaultsToLastra() throws IOException {
+        byte[] payload = "LASTRA-PAYLOAD".getBytes(StandardCharsets.UTF_8);
+        responseBody.set(payload);
+
+        try (InputStream in = qts.tickers("binance", "BTC", "USDT", "2026-01-15T10")) {
+            assertArrayEquals(payload, in.readAllBytes());
+        }
+
+        HttpExchange recorded = exchanges.get(0);
+        assertEquals("/exchange/binance/tickers/BTC/USDT", recorded.getRequestURI().getPath());
+        assertEquals("hour=2026-01-15T10&format=lastra", recorded.getRequestURI().getRawQuery());
+        assertEquals("Bearer test-token", recorded.getRequestHeaders().getFirst("Authorization"));
+    }
+
+    @Test
+    void klinesEmitsParquetFormatWhenRequested() throws IOException {
+        responseBody.set("ok".getBytes(StandardCharsets.UTF_8));
+
+        try (InputStream in = qts.klines("binance", "BTC", "USDT", "2026-01-15T10", DownloadFormat.PARQUET)) {
+            in.readAllBytes();
+        }
+
+        HttpExchange recorded = exchanges.get(0);
+        assertEquals("/exchange/binance/klines/BTC/USDT", recorded.getRequestURI().getPath());
+        assertEquals("hour=2026-01-15T10&format=parquet", recorded.getRequestURI().getRawQuery());
+    }
+
+    @Test
+    void mapsApiExceptionToQtsDownloadError() {
+        responseStatus.set(404);
+        responseBody.set("{\"code\":\"NOT_FOUND\",\"message\":\"hour not backfilled\"}"
+                .getBytes(StandardCharsets.UTF_8));
+
+        QTSDownloadError ex = assertThrows(
+                QTSDownloadError.class,
+                () -> qts.tickers("binance", "BTC", "USDT", "2026-01-15T10"));
+        assertTrue(ex.getMessage().contains("HTTP 404"));
+        assertTrue(ex.getMessage().contains("NOT_FOUND"));
+    }
+}