diff --git a/.gitignore b/.gitignore
index 5d6a15d..19bdf62 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,7 @@
*.class
/out/
/coverage/
+
+# Python cache files
+__pycache__/
+*.py[cod]
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 37fcefa..895bf0e 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
{
- ".": "1.0.0"
+ ".": "2.0.0"
}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6533bfe..1636f1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,13 +1,11 @@
# Changelog
-## 1.0.0
+## 2.0.0
-- Add the Gradle multi-module SDK, shared OkHttp/Jackson transport, typed errors, pagination, polling, and SSE support.
-- Add named AI, agents, and workflows clients plus accessors for every service.
-- Add MockWebServer, README example, route contract, Java 17/21 CI, and Central Portal release checks.
+- Establish the initial SDK release with the multi-module build, shared transport, typed failures, pagination, polling, and SSE support.
+- Add named service clients and operation methods for all catalogued routes.
+- Retry safe streamed GET downloads and bound retained error diagnostics.
+- Add immutable typed query parameters and JSON tree request bodies for routes without contract schemas; isolate custom Jackson configuration.
+- Narrow polling exceptions, complete finite SSE publishers at exact demand boundaries, and publish generated service references.
All notable changes to this SDK are recorded here.
-
-## Unreleased
-
-- Add the initial repository scaffold and shared API contract snapshots.
diff --git a/README.md b/README.md
index c12c860..e75e70d 100644
--- a/README.md
+++ b/README.md
@@ -14,35 +14,87 @@ Maven:
dev.frontal
frontal-sdk
- 1.0.0
+ 2.0.0
```
Gradle Kotlin DSL:
```kotlin
-implementation("dev.frontal:frontal-sdk:1.0.0")
+implementation("dev.frontal:frontal-sdk:2.0.0")
```
Set `FRONTAL_API_KEY`, then make a testable call. The README snippet is compiled and run against MockWebServer in CI:
```java
-try (Frontal f = Frontal.builder().apiKey("frt_test_key").baseUrl(mock.url("/v1").toString()).build()) {
- JsonNode agent = f.agents().get("agt_123", JsonNode.class);
+try (Frontal quickstartClient = Frontal.builder().apiKey("frt_test_key").apiBaseUrl(mock.url("/v1").toString()).build()) {
+ JsonNode agent = quickstartClient.agents().get("agt_123", JsonNode.class);
if (!"triage".equals(agent.path("name").asText())) throw new AssertionError();
}
```
-The production default base URL is `https://api.frontal.dev/v1`; `baseUrl(...)` is useful for tests and compatible gateways. `Frontal` exposes every API service, with named operation helpers for AI, agents, and workflows. Each service shares one transport, and all catalogued routes remain available through its `request` methods and `Endpoints` constants.
+The production default API base URL is `https://api.frontal.dev/v1`; `apiBaseUrl(...)` configures test servers and compatible gateways. `Frontal` exposes a client for every API service, with nested resource clients and concise methods generated from the route catalog. Collection methods use names such as `list()` and `create()`, item methods use `get(id)`, `update(id, body)`, and `delete(id)`, and custom actions keep their action names. Each resource shares one transport; `Endpoints` and generic `request` methods remain available for advanced use.
+
+Nested routes follow their resource path:
+
+```java
+JsonNode run = f.agents().runs().get("run_123", JsonNode.class);
+```
+
+```java
+JsonNode dataset = f.data().ingest().datasets().get("dataset_123", JsonNode.class);
+```
+
+For routes whose contracts do not define a payload schema, named methods accept `JsonNode` request bodies and caller-selected response types. Use `QueryParams` when you need to add query values and `TypeReference` for generic collections:
+
+```java
+ JsonNode health = f.agents().health(JsonNode.class);
+```
## Configuration
-`Frontal.builder()` accepts `apiKey`, `baseUrl`, `aiBaseUrl`, `env`, `debug`, `timeout`, `connectTimeout`, `maxRetries`, and custom headers. `Frontal.fromEnvironment()` reads `FRONTAL_API_KEY`, `FRONTAL_API_URL`, `FRONTAL_AI_URL`, `FRONTAL_ENV`, `FRONTAL_DEBUG`, and `FRONTAL_TIMEOUT`. Java does not load `.env` files automatically.
+`Frontal.builder()` accepts `apiKey`, `apiBaseUrl`, `aiBaseUrl`, `environment`, `debug`, `requestTimeout`, `connectTimeout`, `maxRetries`, `maxResponseBytes`, `maxErrorBodyBytes`, `userAgent`, custom headers, and an optional `ObjectMapper`. The SDK copies a supplied mapper at build time. `Frontal.fromEnvironment()` reads `FRONTAL_API_KEY`, `FRONTAL_API_URL`, `FRONTAL_AI_URL`, `FRONTAL_ENV`, `FRONTAL_DEBUG`, and `FRONTAL_TIMEOUT`. Java does not load `.env` files automatically.
-HTTP errors are `FrontalException` subclasses: `AuthException`, `RateLimitException`, `ValidationException`, `ServerException`, or `ApiException`. They expose `code()`, `requestId()`, `statusCode()`, and `retryable()`. Network failures use `NetworkException`.
+HTTP errors are `FrontalException` subclasses: `AuthException`, `RateLimitException`, `ValidationException`, `ServerException`, or `ApiException`. They expose `code()`, `requestId()`, `statusCode()`, and `retryable()`. Network failures use `NetworkException`. `responseBody()` retains at most 16 KiB by default; `responseBodyTruncated()` reports when the diagnostic body was capped.
+
+With a `Frontal` client open, catch typed failures when the application needs different handling, and use the request ID for support diagnostics. Error response bodies are available through `responseBody()` and may contain sensitive data, so avoid logging them indiscriminately:
+
+```java
+try {
+ JsonNode agent = f.agents().get("agt_123", JsonNode.class);
+} catch (RateLimitException e) {
+ System.err.println("Retry after " + e.retryAfter() + "; request " + e.requestId());
+} catch (FrontalException e) {
+ System.err.println("Frontal request failed: " + e.code() + "; request " + e.requestId());
+}
+```
Paginated list operations return `PageResult` with `nextPage()`, `all()`, and `Iterable` support. Streaming endpoints expose `Flow.Publisher` and a blocking `SseEventIterator` that callers close after use.
+Iterate pages lazily when the result may be large:
+
+```java
+for (JsonNode agent : f.agents().listPages(QueryParams.empty(), JsonNode.class)) {
+ System.out.println(agent.path("id").asText());
+}
+```
+
+`requestBytes()` buffers a response up to the configured response limit. For larger downloads, use `streamBody()` and close the response. This example assumes `outputStream` is an open `OutputStream`:
+
+```java
+Endpoint download = new Endpoint(ApiService.DATA, HttpMethod.GETRAW, "/exports/{param}");
+try (ApiStream response = f.data().streamBody(download, List.of("exp_123"), QueryParams.empty(), null)) {
+ response.body().transferTo(outputStream);
+}
+```
+
+Request and query maps use their keys verbatim as wire names; for example, use `"agent_id"` when the API expects `agent_id`. Java bean properties use the default snake case Jackson strategy. A custom mapper’s settings are honored, and `@JsonProperty` controls exact field names.
+
+The configured request timeout applies to each ordinary call attempt and `streamBody()` download attempt. Safe GET requests may retry up to `maxRetries`; writes run once. Retry delays are capped at five seconds. SSE connections disable the read and call timeout so long-lived streams can remain open; close the blocking iterator or cancel the Flow subscription to release the connection.
+
+
+Browse the [service API reference](./docs/api/README.md) for all named operations and route signatures.
+
## Build and verify
Requirements: JDK 17 or 21 and Python 3 for the contract check. The Gradle wrapper is the supported build entry point.
diff --git a/SECURITY.md b/SECURITY.md
index d3b3567..ba7a227 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -6,6 +6,6 @@ We aim to acknowledge reports within five business days and will coordinate a fi
## Supported versions
-Security fixes are provided for the latest stable release line (currently `1.x`). Upgrade to the latest patch release before reporting an issue. Unsupported versions may receive a fix only when a vulnerability warrants it and a maintainer can provide one.
+Security fixes are provided for the latest stable release line (currently `2.x`). Upgrade to the latest patch release before reporting an issue. Unsupported versions may receive a fix only when a vulnerability warrants it and a maintainer can provide one.
Never commit populated `.env` files, credentials, or captured production payloads.
diff --git a/contracts/reports/conformance.json b/contracts/reports/conformance.json
index aec2e5a..2375227 100644
--- a/contracts/reports/conformance.json
+++ b/contracts/reports/conformance.json
@@ -1,9 +1,10 @@
{
"repository": "sdk-java",
"language": "Java",
- "status": "route-catalogued",
+ "status": "named-operations",
"contractEndpointEntries": 622,
- "generatedEndpointConstants": 622,
- "catalogCoverage": "100%",
- "note": "All routes in sdk-endpoints.json have generated endpoint constants and share the generic SDK transport. Route-specific typed models are not generated because the inventory does not provide complete schemas."
+ "generatedEndpointConstants": 611,
+ "namedOperationMethods": 611,
+ "supportedRouteCoverage": "611/622",
+ "note": "Endpoint constants and named operations cover SDK service routes. Payloads without usable schemas retain caller-provided JSON and response types."
}
diff --git a/contracts/reports/migration-matrix.md b/contracts/reports/migration-matrix.md
index 793eb5b..c006549 100644
--- a/contracts/reports/migration-matrix.md
+++ b/contracts/reports/migration-matrix.md
@@ -1,12 +1,13 @@
# Java SDK route coverage
-_Status: generated route catalog complete. This measures catalog coverage and generic transport availability, not route-specific typed models._
+_Status: generated route catalog and named operation surface complete. Typed models are provided only where committed schemas are usable._
| Metric | Value |
| --- | ---: |
| Contract endpoint entries | 622 |
-| Generated endpoint constants | 622 |
-| Catalog coverage | 100% |
-| Route-specific typed request/response models | Not generated |
+| Generated endpoint constants | 611 |
+| Named operation methods for supported routes | 611 |
+| Contract routes omitted from the SDK surface | 11 |
+| Operation-specific payload schemas usable | Limited by committed contract snapshots |
-`scripts/generate_endpoints.py` regenerates `services/src/main/java/dev/frontal/sdk/resources/Endpoints.java` from `contracts/sdk-endpoints.json`. All catalogued routes use the shared Java transport; callers provide response types when decoding JSON.
+`scripts/generate_endpoints.py` regenerates `services/src/main/java/dev/frontal/sdk/resources/Endpoints.java` from `contracts/sdk-endpoints.json`, grouping agent-run operations with agents. SDK routes use the shared Java transport; callers provide response types when decoding JSON.
diff --git a/core/src/main/java/dev/frontal/sdk/api/ApiClient.java b/core/src/main/java/dev/frontal/sdk/api/ApiClient.java
index 4b1d984..e3329ea 100644
--- a/core/src/main/java/dev/frontal/sdk/api/ApiClient.java
+++ b/core/src/main/java/dev/frontal/sdk/api/ApiClient.java
@@ -4,8 +4,6 @@
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
-import com.fasterxml.jackson.databind.node.ArrayNode;
-import com.fasterxml.jackson.databind.node.ObjectNode;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
@@ -45,11 +43,15 @@ public final class ApiClient implements AutoCloseable {
private final boolean ownsHttpClient;
public ApiClient(ClientConfig config) {
- this(config, createHttpClient(config), new ObjectMapper(), apiKeyAuth(config), true);
+ this(config, createHttpClient(config), defaultObjectMapper(), apiKeyAuth(config), true);
+ }
+
+ ApiClient(ClientConfig config, ObjectMapper objectMapper) {
+ this(config, createHttpClient(config), objectMapper, apiKeyAuth(config), true);
}
public ApiClient(ClientConfig config, AuthProvider authProvider) {
- this(config, createHttpClient(config), new ObjectMapper(), authProvider, true);
+ this(config, createHttpClient(config), defaultObjectMapper(), authProvider, true);
}
public ApiClient(ClientConfig config, OkHttpClient httpClient, ObjectMapper objectMapper) {
@@ -69,15 +71,13 @@ private ApiClient(
boolean ownsHttpClient) {
this.config = Objects.requireNonNull(config, "config");
this.httpClient = Objects.requireNonNull(httpClient, "httpClient");
- this.objectMapper = Objects.requireNonNull(objectMapper, "objectMapper")
- .copy()
- .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
+ this.objectMapper = Objects.requireNonNull(objectMapper, "objectMapper").copy();
this.authProvider = authProvider;
this.ownsHttpClient = ownsHttpClient;
}
public ObjectMapper objectMapper() {
- return objectMapper;
+ return objectMapper.copy();
}
public ClientConfig config() {
@@ -87,8 +87,8 @@ public ClientConfig config() {
public @Nullable T request(
Endpoint endpoint,
List pathParams,
- Map query,
- @Nullable Object body,
+ QueryParams query,
+ @Nullable JsonNode body,
Class responseType)
throws IOException, InterruptedException {
return decode(execute(endpoint, pathParams, query, body).body(), responseType);
@@ -97,8 +97,8 @@ public ClientConfig config() {
public @Nullable T request(
Endpoint endpoint,
List pathParams,
- Map query,
- @Nullable Object body,
+ QueryParams query,
+ @Nullable JsonNode body,
TypeReference responseType)
throws IOException, InterruptedException {
byte[] response = execute(endpoint, pathParams, query, body).body();
@@ -106,14 +106,16 @@ public ClientConfig config() {
}
/** Executes an endpoint and returns the successful status, headers, and raw response bytes. */
- public ApiResponse execute(Endpoint endpoint, List pathParams, Map query, @Nullable Object body)
+ public ApiResponse execute(Endpoint endpoint, List pathParams, QueryParams query, @Nullable JsonNode body)
throws IOException, InterruptedException {
Objects.requireNonNull(endpoint, "endpoint");
- if (endpoint.method() == HttpMethod.STREAM || endpoint.method() == HttpMethod.POSTFORMDATA) {
+ if (endpoint.method() == HttpMethod.STREAM
+ || endpoint.method() == HttpMethod.POSTFORMDATA
+ || endpoint.method() == HttpMethod.POSTRAW) {
throw new IllegalArgumentException("Use stream() or executeForm() for this endpoint kind");
}
RequestBody requestBody = requestBody(endpoint.method(), body);
- String contentType = contentType(endpoint.method(), body);
+ String contentType = contentType(body);
String accept = endpoint.method() == HttpMethod.GETRAW
? "application/pdf, application/octet-stream, */*"
: "application/json, application/octet-stream";
@@ -121,15 +123,104 @@ public ApiResponse execute(Endpoint endpoint, List pathParams, Map pathParams, Map query, @Nullable Object body)
+ public byte[] requestBytes(Endpoint endpoint, List pathParams, QueryParams query, @Nullable JsonNode body)
throws IOException, InterruptedException {
return execute(endpoint, pathParams, query, body).body();
}
+ /** Sends an opaque binary request body and returns response metadata and bytes. */
+ public ApiResponse executeRaw(Endpoint endpoint, List pathParams, QueryParams query, byte[] body)
+ throws IOException, InterruptedException {
+ Objects.requireNonNull(endpoint, "endpoint");
+ Objects.requireNonNull(body, "body");
+ if (endpoint.method() != HttpMethod.POSTRAW) {
+ throw new IllegalArgumentException("executeRaw requires a POSTRAW endpoint");
+ }
+ return exchange(
+ endpoint,
+ pathParams,
+ query,
+ RequestBody.create(body, OCTET_STREAM),
+ OCTET_STREAM.toString(),
+ "application/json, application/octet-stream");
+ }
+
+ /** Sends an opaque binary request body and decodes the response. */
+ public @Nullable T requestRaw(
+ Endpoint endpoint, List pathParams, QueryParams query, byte[] body, Class responseType)
+ throws IOException, InterruptedException {
+ return decode(executeRaw(endpoint, pathParams, query, body).body(), responseType);
+ }
+
+ /** Sends an opaque binary request body and decodes a generic response. */
+ public @Nullable T requestRaw(
+ Endpoint endpoint, List pathParams, QueryParams query, byte[] body, TypeReference responseType)
+ throws IOException, InterruptedException {
+ byte[] response = executeRaw(endpoint, pathParams, query, body).body();
+ return response.length == 0 ? null : objectMapper.readValue(response, responseType);
+ }
+
+ /** Sends an opaque binary request body and returns raw response bytes. */
+ public byte[] requestRawBytes(Endpoint endpoint, List pathParams, QueryParams query, byte[] body)
+ throws IOException, InterruptedException {
+ return executeRaw(endpoint, pathParams, query, body).body();
+ }
+
+ /** Opens a successful response body without buffering it. The caller must close the result. */
+ public ApiStream streamBody(Endpoint endpoint, List pathParams, QueryParams query, @Nullable JsonNode body)
+ throws IOException, InterruptedException {
+ Objects.requireNonNull(endpoint, "endpoint");
+ if (endpoint.method() == HttpMethod.STREAM
+ || endpoint.method() == HttpMethod.POSTFORMDATA
+ || endpoint.method() == HttpMethod.POSTRAW) {
+ throw new IllegalArgumentException("Use streamResponse() or executeForm() for this endpoint kind");
+ }
+ String requestId = UUID.randomUUID().toString();
+ RequestBody requestBody = requestBody(endpoint.method(), body);
+ String contentType = contentType(body);
+ int attempts = endpoint.method().wireMethod().equals("GET") ? config.maxRetries() + 1 : 1;
+ for (int attempt = 0; attempt < attempts; attempt++) {
+ Request request = buildRequest(endpoint, pathParams, query, requestBody, contentType, "*/*", requestId);
+ Response response;
+ try {
+ response = httpClient.newCall(request).execute();
+ } catch (IOException exception) {
+ if (attempt + 1 < attempts) {
+ waitBeforeRetry(attempt, null);
+ continue;
+ }
+ throw new NetworkException("Frontal request failed before receiving a response", requestId, exception);
+ }
+ if (!response.isSuccessful()) {
+ int status = response.code();
+ String responseRequestId = response.header("x-request-id", requestId);
+ String retryAfter = response.header("retry-after");
+ ErrorBody errorBody;
+ try (response) {
+ ResponseBody bodyValue = response.body();
+ errorBody =
+ readErrorBody(bodyValue == null ? InputStream.nullInputStream() : bodyValue.byteStream());
+ }
+ if (endpoint.method().wireMethod().equals("GET")
+ && attempt + 1 < attempts
+ && isRetryableStatus(status)) {
+ waitBeforeRetry(attempt, retryAfter);
+ continue;
+ }
+ throw toFrontalException(status, responseRequestId, retryAfter, errorBody);
+ }
+ ResponseBody responseBody = response.body();
+ InputStream input = responseBody == null ? InputStream.nullInputStream() : responseBody.byteStream();
+ return new ApiStream(
+ response.code(), response.headers().toMultimap(), new ResponseInputStream(response, input));
+ }
+ throw new NetworkException("Frontal request failed", requestId, null);
+ }
+
public @Nullable T requestForm(
Endpoint endpoint,
List pathParams,
- Map query,
+ QueryParams query,
Map fields,
Map files,
Class responseType)
@@ -140,7 +231,7 @@ public byte[] requestBytes(Endpoint endpoint, List pathParams, Map @Nullable T requestForm(
Endpoint endpoint,
List pathParams,
- Map query,
+ QueryParams query,
Map fields,
Map files,
TypeReference responseType)
@@ -154,7 +245,7 @@ public byte[] requestBytes(Endpoint endpoint, List pathParams, Map pathParams,
- Map query,
+ QueryParams query,
Map fields,
Map files)
throws IOException, InterruptedException {
@@ -178,18 +269,18 @@ public ApiResponse executeForm(
}
/** Returns a live response body for a contract endpoint marked {@code STREAM}. */
- public InputStream stream(Endpoint endpoint, List pathParams, Map query)
+ public InputStream stream(Endpoint endpoint, List pathParams, QueryParams query)
throws IOException, InterruptedException {
return streamResponse(endpoint, pathParams, query).body();
}
/** Opens a streaming response while preserving its status and headers. */
- public ApiStream streamResponse(Endpoint endpoint, List pathParams, Map query)
+ public ApiStream streamResponse(Endpoint endpoint, List pathParams, QueryParams query)
throws IOException, InterruptedException {
return newPendingStream(endpoint, pathParams, query).execute();
}
- private PendingStream newPendingStream(Endpoint endpoint, List pathParams, Map query) {
+ private PendingStream newPendingStream(Endpoint endpoint, List pathParams, QueryParams query) {
Objects.requireNonNull(endpoint, "endpoint");
if (endpoint.method() != HttpMethod.STREAM) {
throw new IllegalArgumentException("stream requires a STREAM endpoint");
@@ -222,16 +313,16 @@ private ApiStream execute() throws IOException {
}
ResponseBody responseBody = response.body();
if (!response.isSuccessful()) {
- byte[] bytes;
+ ErrorBody errorBody;
try (response) {
- bytes = readBounded(
+ errorBody = readErrorBody(
responseBody == null ? InputStream.nullInputStream() : responseBody.byteStream());
}
throw toFrontalException(
response.code(),
response.header("x-request-id", requestId),
response.header("retry-after"),
- bytes);
+ errorBody);
}
if (responseBody == null) {
response.close();
@@ -246,7 +337,7 @@ private void cancel() {
}
/** Returns a backpressure-aware publisher of SSE event data. */
- public Flow.Publisher streamPublisher(Endpoint endpoint, List pathParams, Map query) {
+ public Flow.Publisher streamPublisher(Endpoint endpoint, List pathParams, QueryParams query) {
return SseEventPublisher.cancellable(() -> {
PendingStream pending = newPendingStream(endpoint, pathParams, query);
return new SseEventPublisher.StreamSource() {
@@ -264,7 +355,7 @@ public void cancel() {
}
/** Returns a blocking iterator over SSE event data. The caller must close it. */
- public SseEventIterator streamEvents(Endpoint endpoint, List pathParams, Map query)
+ public SseEventIterator streamEvents(Endpoint endpoint, List pathParams, QueryParams query)
throws IOException, InterruptedException {
return new SseEventIterator(streamResponse(endpoint, pathParams, query));
}
@@ -272,7 +363,7 @@ public SseEventIterator streamEvents(Endpoint endpoint, List pathParams,
private ApiResponse exchange(
Endpoint endpoint,
List pathParams,
- Map query,
+ QueryParams query,
@Nullable RequestBody requestBody,
@Nullable String contentType,
String accept)
@@ -292,6 +383,7 @@ private ApiResponse exchange(
throw new NetworkException("Frontal request failed before receiving a response", requestId, exception);
}
byte[] responseBytes;
+ @Nullable ErrorBody errorBody = null;
int status;
String responseRequestId;
String retryAfter;
@@ -302,7 +394,17 @@ private ApiResponse exchange(
retryAfter = response.header("retry-after");
responseHeaders = response.headers().toMultimap();
ResponseBody responseBody = response.body();
- responseBytes = responseBody == null ? new byte[0] : readBounded(responseBody.byteStream());
+ if (responseBody == null) {
+ responseBytes = new byte[0];
+ if (status < 200 || status >= 300) {
+ errorBody = new ErrorBody(responseBytes, false);
+ }
+ } else if (status >= 200 && status < 300) {
+ responseBytes = readBounded(responseBody.byteStream());
+ } else {
+ errorBody = readErrorBody(responseBody.byteStream());
+ responseBytes = errorBody.body();
+ }
}
if (status >= 200 && status < 300) {
return new ApiResponse(status, responseHeaders, responseBytes);
@@ -311,7 +413,7 @@ private ApiResponse exchange(
waitBeforeRetry(attempt, retryAfter);
continue;
}
- throw toFrontalException(status, responseRequestId, retryAfter, responseBytes);
+ throw toFrontalException(status, responseRequestId, retryAfter, Objects.requireNonNull(errorBody));
}
throw new NetworkException("Frontal request failed", requestId, null);
}
@@ -319,7 +421,7 @@ private ApiResponse exchange(
private Request buildRequest(
Endpoint endpoint,
List pathParams,
- Map query,
+ QueryParams query,
@Nullable RequestBody body,
@Nullable String contentType,
String accept,
@@ -353,7 +455,7 @@ private Request buildRequest(
return builder.method(method, effectiveBody).build();
}
- private @Nullable RequestBody requestBody(HttpMethod method, @Nullable Object body) throws IOException {
+ private @Nullable RequestBody requestBody(HttpMethod method, @Nullable JsonNode body) throws IOException {
if (body == null) {
return null;
}
@@ -365,43 +467,21 @@ private Request buildRequest(
throw new IllegalArgumentException("This endpoint does not accept a request body");
}
if (method == HttpMethod.POSTRAW) {
- if (!(body instanceof byte[] bytes)) {
- throw new IllegalArgumentException("POSTRAW request bodies must be byte[]");
- }
- return RequestBody.create(bytes, OCTET_STREAM);
+ throw new IllegalArgumentException("Use executeRaw() for POSTRAW endpoint request bodies");
}
- JsonNode tree = objectMapper.valueToTree(body);
- return RequestBody.create(objectMapper.writeValueAsBytes(camelToSnake(tree)), JSON);
+ return RequestBody.create(objectMapper.writeValueAsBytes(body), JSON);
}
- private @Nullable String contentType(HttpMethod method, @Nullable Object body) {
+ private @Nullable String contentType(@Nullable JsonNode body) {
if (body == null) {
return null;
}
- return method == HttpMethod.POSTRAW ? OCTET_STREAM.toString() : JSON.toString();
- }
-
- private JsonNode camelToSnake(JsonNode node) {
- if (node.isObject()) {
- ObjectNode converted = objectMapper.createObjectNode();
- node.fields()
- .forEachRemaining(entry -> converted.set(toSnake(entry.getKey()), camelToSnake(entry.getValue())));
- return converted;
- }
- if (node.isArray()) {
- ArrayNode converted = objectMapper.createArrayNode();
- node.forEach(item -> converted.add(camelToSnake(item)));
- return converted;
- }
- return node;
- }
-
- private String toSnake(String key) {
- return key.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toLowerCase(java.util.Locale.ROOT);
+ return JSON.toString();
}
private FrontalException toFrontalException(
- int status, String requestId, @Nullable String retryAfter, byte[] body) {
+ int status, String requestId, @Nullable String retryAfter, ErrorBody errorBody) {
+ byte[] body = errorBody.body();
String responseBody = new String(body, StandardCharsets.UTF_8);
@Nullable String code = null;
@Nullable String message = null;
@@ -418,18 +498,19 @@ private FrontalException toFrontalException(
// Preserve plain-text error bodies in the exception.
}
if (status == 401 || status == 403) {
- return new AuthException(code, message, requestId, status);
+ return new AuthException(code, message, requestId, status, responseBody, errorBody.truncated());
}
if (status == 400 || status == 422) {
- return new ValidationException(code, message, requestId, status);
+ return new ValidationException(code, message, requestId, status, responseBody, errorBody.truncated());
}
if (status == 429) {
- return new RateLimitException(code, message, requestId, parseRetryAfter(retryAfter));
+ return new RateLimitException(
+ code, message, requestId, parseRetryAfter(retryAfter), responseBody, errorBody.truncated());
}
if (status >= 500) {
- return new ServerException(code, message, requestId, status, responseBody);
+ return new ServerException(code, message, requestId, status, responseBody, errorBody.truncated());
}
- return new ApiException(status, code, message, requestId, responseBody);
+ return new ApiException(status, code, message, requestId, responseBody, errorBody.truncated());
}
private @Nullable String textOrNull(JsonNode node) {
@@ -454,13 +535,49 @@ private byte[] readBounded(InputStream stream) throws IOException {
}
}
+ private ErrorBody readErrorBody(InputStream stream) throws IOException {
+ ByteArrayOutputStream output = new ByteArrayOutputStream(Math.min(config.maxErrorBodyBytes(), 8192));
+ byte[] buffer = new byte[8192];
+ int remaining = config.maxErrorBodyBytes();
+ int read;
+ while (remaining > 0 && (read = stream.read(buffer, 0, Math.min(buffer.length, remaining))) >= 0) {
+ output.write(buffer, 0, read);
+ remaining -= read;
+ }
+ boolean truncated = remaining == 0 && stream.read() >= 0;
+ return new ErrorBody(output.toByteArray(), truncated);
+ }
+
+ private static final class ErrorBody {
+ private final byte[] body;
+ private final boolean truncated;
+
+ private ErrorBody(byte[] body, boolean truncated) {
+ this.body = body;
+ this.truncated = truncated;
+ }
+
+ private byte[] body() {
+ return body;
+ }
+
+ private boolean truncated() {
+ return truncated;
+ }
+ }
+
private void waitBeforeRetry(int attempt, @Nullable String retryAfter) throws InterruptedException {
long delayMillis = Math.min(5_000L, 100L << Math.min(attempt, 5));
Duration serverDelay = parseRetryAfter(retryAfter);
if (retryAfter != null && !retryAfter.isBlank()) {
- delayMillis = Math.min(5_000L, serverDelay.toMillis());
+ delayMillis = serverDelay.compareTo(Duration.ofSeconds(5)) >= 0 ? 5_000L : serverDelay.toMillis();
+ }
+ try {
+ TimeUnit.MILLISECONDS.sleep(delayMillis);
+ } catch (InterruptedException exception) {
+ Thread.currentThread().interrupt();
+ throw exception;
}
- TimeUnit.MILLISECONDS.sleep(delayMillis);
}
private Duration parseRetryAfter(@Nullable String retryAfter) {
@@ -518,6 +635,28 @@ private static OkHttpClient createHttpClient(ClientConfig config) {
.build();
}
+ private static ObjectMapper defaultObjectMapper() {
+ return new ObjectMapper().setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
+ }
+
+ private static final class ResponseInputStream extends java.io.FilterInputStream {
+ private final Response response;
+
+ private ResponseInputStream(Response response, InputStream input) {
+ super(input);
+ this.response = response;
+ }
+
+ @Override
+ public void close() throws IOException {
+ try {
+ super.close();
+ } finally {
+ response.close();
+ }
+ }
+ }
+
private static @Nullable AuthProvider apiKeyAuth(ClientConfig config) {
@Nullable String apiKey = config.apiKey();
return apiKey == null ? null : new ApiKeyAuthProvider(apiKey);
diff --git a/core/src/main/java/dev/frontal/sdk/auth/ApiKeyAuthProvider.java b/core/src/main/java/dev/frontal/sdk/auth/ApiKeyAuthProvider.java
index 4888168..f2b08b3 100644
--- a/core/src/main/java/dev/frontal/sdk/auth/ApiKeyAuthProvider.java
+++ b/core/src/main/java/dev/frontal/sdk/auth/ApiKeyAuthProvider.java
@@ -9,8 +9,8 @@ public final class ApiKeyAuthProvider implements AuthProvider {
public ApiKeyAuthProvider(String apiKey) {
Objects.requireNonNull(apiKey, "apiKey");
- if (apiKey.isBlank()) {
- throw new IllegalArgumentException("apiKey must not be blank");
+ if (apiKey.isBlank() || apiKey.indexOf('\r') >= 0 || apiKey.indexOf('\n') >= 0) {
+ throw new IllegalArgumentException("apiKey must be nonblank and contain no line breaks");
}
this.apiKey = apiKey;
}
diff --git a/core/src/main/java/dev/frontal/sdk/config/ClientConfig.java b/core/src/main/java/dev/frontal/sdk/config/ClientConfig.java
index 106cb09..641b91c 100644
--- a/core/src/main/java/dev/frontal/sdk/config/ClientConfig.java
+++ b/core/src/main/java/dev/frontal/sdk/config/ClientConfig.java
@@ -20,6 +20,7 @@ public final class ClientConfig {
private final Duration requestTimeout;
private final int maxRetries;
private final long maxResponseBytes;
+ private final int maxErrorBodyBytes;
private final String userAgent;
private final String environment;
private final boolean debug;
@@ -37,12 +38,25 @@ private ClientConfig(Builder builder) {
if (builder.maxResponseBytes <= 0) {
throw new IllegalArgumentException("maxResponseBytes must be positive");
}
+ if (builder.maxErrorBodyBytes <= 0) {
+ throw new IllegalArgumentException("maxErrorBodyBytes must be positive");
+ }
maxRetries = builder.maxRetries;
maxResponseBytes = builder.maxResponseBytes;
+ maxErrorBodyBytes = builder.maxErrorBodyBytes;
userAgent = requireText(builder.userAgent, "userAgent");
environment = requireText(builder.environment, "environment").toLowerCase(Locale.ROOT);
debug = builder.debug;
- headers = Map.copyOf(builder.headers);
+ Map validatedHeaders = new LinkedHashMap<>();
+ java.util.Set normalizedNames = new java.util.HashSet<>();
+ builder.headers.forEach((name, value) -> {
+ validateHeader(name, value);
+ if (!normalizedNames.add(name.toLowerCase(Locale.ROOT))) {
+ throw new IllegalArgumentException("Duplicate header name ignoring case: " + name);
+ }
+ validatedHeaders.put(name, value);
+ });
+ headers = Map.copyOf(validatedHeaders);
}
/** Creates the default configuration without authentication. */
@@ -55,23 +69,6 @@ public ClientConfig(String apiKey) {
this(builder().apiKey(apiKey));
}
- /** Compatibility constructor for explicit connection settings. */
- public ClientConfig(
- String apiKey,
- URI baseUrl,
- Duration timeout,
- int maxRetries,
- long maxResponseBytes,
- Map headers) {
- this(builder()
- .apiKey(apiKey)
- .apiBaseUrl(baseUrl)
- .requestTimeout(timeout)
- .maxRetries(maxRetries)
- .maxResponseBytes(maxResponseBytes)
- .headers(headers));
- }
-
public static Builder builder() {
return new Builder();
}
@@ -122,11 +119,6 @@ public URI aiBaseUrl() {
return aiBaseUrl;
}
- /** Returns the general API base URL for compatibility with earlier SDK versions. */
- public URI baseUrl() {
- return apiBaseUrl;
- }
-
public Duration connectTimeout() {
return connectTimeout;
}
@@ -135,11 +127,6 @@ public Duration requestTimeout() {
return requestTimeout;
}
- /** Returns the request timeout for compatibility with earlier SDK versions. */
- public Duration timeout() {
- return requestTimeout;
- }
-
public int maxRetries() {
return maxRetries;
}
@@ -148,6 +135,11 @@ public long maxResponseBytes() {
return maxResponseBytes;
}
+ /** Maximum error response bytes retained for diagnostics. */
+ public int maxErrorBodyBytes() {
+ return maxErrorBodyBytes;
+ }
+
public String userAgent() {
return userAgent;
}
@@ -170,6 +162,9 @@ private static URI normalizeBaseUrl(URI value, String name) {
if (value.getHost() == null || !("http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme))) {
throw new IllegalArgumentException(name + " must be an absolute HTTP or HTTPS URL");
}
+ if (value.getRawUserInfo() != null || value.getRawQuery() != null || value.getRawFragment() != null) {
+ throw new IllegalArgumentException(name + " must not include user info, a query, or a fragment");
+ }
String normalized = value.toString();
while (normalized.endsWith("/")) {
normalized = normalized.substring(0, normalized.length() - 1);
@@ -193,6 +188,24 @@ private static String requireText(String value, String name) {
return value;
}
+ private static void validateHeader(String name, String value) {
+ requireText(name, "header name");
+ Objects.requireNonNull(value, "header value");
+ for (int index = 0; index < name.length(); index++) {
+ char character = name.charAt(index);
+ boolean valid = (character >= '0' && character <= '9')
+ || (character >= 'A' && character <= 'Z')
+ || (character >= 'a' && character <= 'z')
+ || "!#$%&'*+-.^_`|~".indexOf(character) >= 0;
+ if (!valid) {
+ throw new IllegalArgumentException("Invalid HTTP header name: " + name);
+ }
+ }
+ if (value.indexOf('\r') >= 0 || value.indexOf('\n') >= 0) {
+ throw new IllegalArgumentException("HTTP header values must not contain line breaks");
+ }
+ }
+
/** Mutable builder used to create an immutable client configuration. */
public static final class Builder {
private @Nullable String apiKey;
@@ -202,7 +215,8 @@ public static final class Builder {
private Duration requestTimeout = Duration.ofSeconds(30);
private int maxRetries = 2;
private long maxResponseBytes = 64L * 1024 * 1024;
- private String userAgent = "frontal-java-sdk/1.0.0";
+ private int maxErrorBodyBytes = 16 * 1024;
+ private String userAgent = "frontal-java-sdk/2.0.0";
private String environment = "development";
private boolean debug;
private final Map headers = new LinkedHashMap<>();
@@ -211,9 +225,6 @@ private Builder() {}
public Builder apiKey(String apiKey) {
String value = requireText(apiKey, "apiKey");
- if (!value.startsWith("frt_")) {
- throw new IllegalArgumentException("apiKey must start with frt_");
- }
this.apiKey = value;
return this;
}
@@ -227,15 +238,6 @@ public Builder apiBaseUrl(URI apiBaseUrl) {
return this;
}
- /** Alias for {@link #apiBaseUrl(URI)}. */
- public Builder baseUrl(URI baseUrl) {
- return apiBaseUrl(baseUrl);
- }
-
- public Builder baseUrl(String baseUrl) {
- return apiBaseUrl(baseUrl);
- }
-
public Builder aiBaseUrl(String aiBaseUrl) {
return aiBaseUrl(URI.create(aiBaseUrl));
}
@@ -255,11 +257,6 @@ public Builder requestTimeout(Duration requestTimeout) {
return this;
}
- /** Alias for {@link #requestTimeout(Duration)}. */
- public Builder timeout(Duration timeout) {
- return requestTimeout(timeout);
- }
-
public Builder maxRetries(int maxRetries) {
this.maxRetries = maxRetries;
return this;
@@ -270,6 +267,11 @@ public Builder maxResponseBytes(long maxResponseBytes) {
return this;
}
+ public Builder maxErrorBodyBytes(int maxErrorBodyBytes) {
+ this.maxErrorBodyBytes = maxErrorBodyBytes;
+ return this;
+ }
+
public Builder userAgent(String userAgent) {
this.userAgent = userAgent;
return this;
diff --git a/core/src/main/java/dev/frontal/sdk/models/ApiException.java b/core/src/main/java/dev/frontal/sdk/models/ApiException.java
index b5b6c49..0422cdb 100644
--- a/core/src/main/java/dev/frontal/sdk/models/ApiException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/ApiException.java
@@ -4,19 +4,30 @@
/** An HTTP error outside the more specific authentication, validation, rate, or server classes. */
public final class ApiException extends FrontalException {
- private final String responseBody;
-
public ApiException(
int statusCode,
@Nullable String code,
@Nullable String message,
@Nullable String requestId,
String responseBody) {
- super(code, message, requestId, statusCode, statusCode == 408 || statusCode == 425);
- this.responseBody = responseBody;
+ this(statusCode, code, message, requestId, responseBody, false);
}
- public String responseBody() {
- return responseBody;
+ public ApiException(
+ int statusCode,
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ String responseBody,
+ boolean responseBodyTruncated) {
+ super(
+ code,
+ message,
+ requestId,
+ statusCode,
+ statusCode == 408 || statusCode == 425,
+ null,
+ responseBody,
+ responseBodyTruncated);
}
}
diff --git a/core/src/main/java/dev/frontal/sdk/models/ApiService.java b/core/src/main/java/dev/frontal/sdk/models/ApiService.java
index b338960..74246aa 100644
--- a/core/src/main/java/dev/frontal/sdk/models/ApiService.java
+++ b/core/src/main/java/dev/frontal/sdk/models/ApiService.java
@@ -1,6 +1,6 @@
package dev.frontal.sdk;
-/** Service domains exposed by the Frontal API. */
+/** Contract route groups used to identify endpoint ownership. */
public enum ApiService {
AGENTS("agents"),
AI("ai"),
@@ -20,10 +20,8 @@ public enum ApiService {
SCHEDULES("schedules"),
WEBHOOKS("webhooks"),
WORKFLOWS("workflows"),
- ACTION_RUNS("action-runs"),
CONNECTION_TESTS("connection-tests"),
EVENTS("events"),
- INTEGRATIONS("integrations"),
INVOCATIONS("invocations"),
PROVIDERS("providers"),
WEBHOOK_ENDPOINTS("webhook-endpoints");
diff --git a/core/src/main/java/dev/frontal/sdk/models/AuthException.java b/core/src/main/java/dev/frontal/sdk/models/AuthException.java
index 35c38c1..dbb2ac2 100644
--- a/core/src/main/java/dev/frontal/sdk/models/AuthException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/AuthException.java
@@ -5,6 +5,25 @@
/** Authentication or authorization failure returned by the API. */
public final class AuthException extends FrontalException {
public AuthException(@Nullable String code, @Nullable String message, @Nullable String requestId, int statusCode) {
- super(code, message, requestId, statusCode, false);
+ this(code, message, requestId, statusCode, null);
+ }
+
+ public AuthException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ @Nullable String responseBody) {
+ this(code, message, requestId, statusCode, responseBody, false);
+ }
+
+ public AuthException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ @Nullable String responseBody,
+ boolean responseBodyTruncated) {
+ super(code, message, requestId, statusCode, false, null, responseBody, responseBodyTruncated);
}
}
diff --git a/core/src/main/java/dev/frontal/sdk/models/FrontalException.java b/core/src/main/java/dev/frontal/sdk/models/FrontalException.java
index 577af81..feb0d08 100644
--- a/core/src/main/java/dev/frontal/sdk/models/FrontalException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/FrontalException.java
@@ -17,6 +17,8 @@ public abstract sealed class FrontalException extends IOException
private final String requestId;
private final int statusCode;
private final boolean retryable;
+ private final @Nullable String responseBody;
+ private final boolean responseBodyTruncated;
protected FrontalException(
@Nullable String code,
@@ -30,6 +32,8 @@ protected FrontalException(
Objects.requireNonNullElseGet(requestId, () -> UUID.randomUUID().toString());
this.statusCode = statusCode;
this.retryable = retryable;
+ this.responseBody = null;
+ this.responseBodyTruncated = false;
}
protected FrontalException(
@@ -45,6 +49,38 @@ protected FrontalException(
Objects.requireNonNullElseGet(requestId, () -> UUID.randomUUID().toString());
this.statusCode = statusCode;
this.retryable = retryable;
+ this.responseBody = null;
+ this.responseBodyTruncated = false;
+ }
+
+ protected FrontalException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ boolean retryable,
+ @Nullable Throwable cause,
+ @Nullable String responseBody) {
+ this(code, message, requestId, statusCode, retryable, cause, responseBody, false);
+ }
+
+ protected FrontalException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ boolean retryable,
+ @Nullable Throwable cause,
+ @Nullable String responseBody,
+ boolean responseBodyTruncated) {
+ super(message == null || message.isBlank() ? "Frontal request failed" : message, cause);
+ this.code = Objects.requireNonNullElse(code, "UNKNOWN_ERROR");
+ this.requestId =
+ Objects.requireNonNullElseGet(requestId, () -> UUID.randomUUID().toString());
+ this.statusCode = statusCode;
+ this.retryable = retryable;
+ this.responseBody = responseBody;
+ this.responseBodyTruncated = responseBodyTruncated;
}
public final String code() {
@@ -62,4 +98,14 @@ public final int statusCode() {
public final boolean retryable() {
return retryable;
}
+
+ /** Raw response body when the API returned one; may contain sensitive data. */
+ public final @Nullable String responseBody() {
+ return responseBody;
+ }
+
+ /** Whether the retained response body was truncated to the configured diagnostic limit. */
+ public final boolean responseBodyTruncated() {
+ return responseBodyTruncated;
+ }
}
diff --git a/core/src/main/java/dev/frontal/sdk/models/PageResult.java b/core/src/main/java/dev/frontal/sdk/models/PageResult.java
index fe43596..fa4dd48 100644
--- a/core/src/main/java/dev/frontal/sdk/models/PageResult.java
+++ b/core/src/main/java/dev/frontal/sdk/models/PageResult.java
@@ -2,10 +2,12 @@
import java.io.IOException;
import java.util.ArrayList;
+import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Objects;
+import java.util.Set;
import org.jspecify.annotations.Nullable;
/** A page of data with a lazy cursor-based next-page loader. */
@@ -32,13 +34,21 @@ public Pagination pagination() {
if (!pagination.hasMore() || nextPageLoader == null) {
return null;
}
- return nextPageLoader.load(pagination.cursor());
+ PageResult next = nextPageLoader.load(pagination.cursor());
+ if (next != null && next.pagination.hasMore() && pagination.cursor().equals(next.pagination.cursor())) {
+ throw new IOException("Pagination cursor did not advance: " + pagination.cursor());
+ }
+ return next;
}
public List all() throws IOException, InterruptedException {
List items = new ArrayList<>(data);
PageResult page = this;
+ Set requestedCursors = new HashSet<>();
while (page.pagination.hasMore()) {
+ if (!requestedCursors.add(page.pagination.cursor())) {
+ throw new IOException("Pagination cursor repeated: " + page.pagination.cursor());
+ }
page = page.nextPage();
if (page == null) {
break;
@@ -53,6 +63,7 @@ public Iterator iterator() {
return new Iterator<>() {
private @Nullable PageResult current = PageResult.this;
private int offset;
+ private final Set requestedCursors = new HashSet<>();
@Override
public boolean hasNext() {
@@ -61,6 +72,9 @@ public boolean hasNext() {
current = null;
return false;
}
+ if (!requestedCursors.add(current.pagination.cursor())) {
+ throw new IllegalStateException("Pagination cursor repeated: " + current.pagination.cursor());
+ }
try {
current = current.nextPage();
} catch (IOException exception) {
diff --git a/core/src/main/java/dev/frontal/sdk/models/QueryParams.java b/core/src/main/java/dev/frontal/sdk/models/QueryParams.java
new file mode 100644
index 0000000..7275d12
--- /dev/null
+++ b/core/src/main/java/dev/frontal/sdk/models/QueryParams.java
@@ -0,0 +1,83 @@
+package dev.frontal.sdk;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/** Immutable typed query parameters. Add the same name more than once to send repeated values. */
+public final class QueryParams {
+ private static final QueryParams EMPTY = new QueryParams(Map.of());
+
+ private final Map> values;
+
+ private QueryParams(Map> values) {
+ this.values = values;
+ }
+
+ /** Returns a reusable empty query parameter set. */
+ public static QueryParams empty() {
+ return EMPTY;
+ }
+
+ /** Creates a builder for query parameters. */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** Creates a single string query parameter. */
+ public static QueryParams of(String name, String value) {
+ return builder().add(name, value).build();
+ }
+
+ Map> values() {
+ return values;
+ }
+
+ /** Mutable builder used to create an immutable query parameter set. */
+ public static final class Builder {
+ private final Map> values = new LinkedHashMap<>();
+
+ /** Adds a string query value. */
+ public Builder add(String name, String value) {
+ requireName(name);
+ values.computeIfAbsent(name, ignored -> new ArrayList<>()).add(Objects.requireNonNull(value, "value"));
+ return this;
+ }
+
+ /** Adds a numeric query value. */
+ public Builder add(String name, Number value) {
+ return add(name, Objects.requireNonNull(value, "value").toString());
+ }
+
+ /** Adds a boolean query value. */
+ public Builder add(String name, boolean value) {
+ return add(name, Boolean.toString(value));
+ }
+
+ /** Adds repeated string values. */
+ public Builder addAll(String name, Iterable values) {
+ Objects.requireNonNull(values, "values").forEach(value -> add(name, value));
+ return this;
+ }
+
+ /** Builds immutable query parameters. */
+ public QueryParams build() {
+ if (values.isEmpty()) {
+ return QueryParams.empty();
+ }
+ Map> copy = new LinkedHashMap<>();
+ values.forEach((name, items) -> copy.put(name, List.copyOf(items)));
+ return new QueryParams(Collections.unmodifiableMap(copy));
+ }
+
+ private static void requireName(String name) {
+ Objects.requireNonNull(name, "name");
+ if (name.isBlank()) {
+ throw new IllegalArgumentException("Query parameter names must not be blank");
+ }
+ }
+ }
+}
diff --git a/core/src/main/java/dev/frontal/sdk/models/RateLimitException.java b/core/src/main/java/dev/frontal/sdk/models/RateLimitException.java
index 0391483..c2df113 100644
--- a/core/src/main/java/dev/frontal/sdk/models/RateLimitException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/RateLimitException.java
@@ -10,7 +10,26 @@ public final class RateLimitException extends FrontalException {
public RateLimitException(
@Nullable String code, @Nullable String message, @Nullable String requestId, Duration retryAfter) {
- super(code, message, requestId, 429, true);
+ this(code, message, requestId, retryAfter, null);
+ }
+
+ public RateLimitException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ Duration retryAfter,
+ @Nullable String responseBody) {
+ this(code, message, requestId, retryAfter, responseBody, false);
+ }
+
+ public RateLimitException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ Duration retryAfter,
+ @Nullable String responseBody,
+ boolean responseBodyTruncated) {
+ super(code, message, requestId, 429, true, null, responseBody, responseBodyTruncated);
this.retryAfter = Objects.requireNonNull(retryAfter, "retryAfter");
}
diff --git a/core/src/main/java/dev/frontal/sdk/models/ServerException.java b/core/src/main/java/dev/frontal/sdk/models/ServerException.java
index bc7095a..206def0 100644
--- a/core/src/main/java/dev/frontal/sdk/models/ServerException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/ServerException.java
@@ -4,20 +4,31 @@
/** The API returned a server-side failure. */
public final class ServerException extends FrontalException {
- private final String responseBody;
-
public ServerException(
@Nullable String code,
@Nullable String message,
@Nullable String requestId,
int statusCode,
String responseBody) {
- super(code, message, requestId, statusCode, isRetryableStatus(statusCode));
- this.responseBody = responseBody;
+ this(code, message, requestId, statusCode, responseBody, false);
}
- public String responseBody() {
- return responseBody;
+ public ServerException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ String responseBody,
+ boolean responseBodyTruncated) {
+ super(
+ code,
+ message,
+ requestId,
+ statusCode,
+ isRetryableStatus(statusCode),
+ null,
+ responseBody,
+ responseBodyTruncated);
}
static boolean isRetryableStatus(int statusCode) {
diff --git a/core/src/main/java/dev/frontal/sdk/models/SseEventIterator.java b/core/src/main/java/dev/frontal/sdk/models/SseEventIterator.java
index d1d89cc..501ee02 100644
--- a/core/src/main/java/dev/frontal/sdk/models/SseEventIterator.java
+++ b/core/src/main/java/dev/frontal/sdk/models/SseEventIterator.java
@@ -32,12 +32,13 @@ public boolean hasNext() {
return false;
}
StringBuilder data = new StringBuilder();
+ boolean sawData = false;
try {
while (true) {
String line = reader.readLine();
if (line == null) {
close();
- if (data.isEmpty()) {
+ if (!sawData) {
return false;
}
next = data.toString();
@@ -45,7 +46,7 @@ public boolean hasNext() {
return true;
}
if (line.isEmpty()) {
- if (!data.isEmpty()) {
+ if (sawData) {
next = data.toString();
ready = true;
return true;
@@ -62,10 +63,11 @@ public boolean hasNext() {
if (value.startsWith(" ")) {
value = value.substring(1);
}
- if (!data.isEmpty()) {
+ if (sawData) {
data.append('\n');
}
data.append(value);
+ sawData = true;
}
}
} catch (IOException exception) {
@@ -85,6 +87,10 @@ public String next() {
return value;
}
+ boolean isExhausted() {
+ return closed && !ready;
+ }
+
@Override
public void close() throws IOException {
if (!closed) {
diff --git a/core/src/main/java/dev/frontal/sdk/models/SseEventPublisher.java b/core/src/main/java/dev/frontal/sdk/models/SseEventPublisher.java
index 170836a..8dd944c 100644
--- a/core/src/main/java/dev/frontal/sdk/models/SseEventPublisher.java
+++ b/core/src/main/java/dev/frontal/sdk/models/SseEventPublisher.java
@@ -122,11 +122,11 @@ private void run() {
if (isCancelled()) {
return;
}
- if (!activeIterator.hasNext()) {
- complete();
+ if (!awaitDemand()) {
return;
}
- if (!awaitDemand()) {
+ if (!activeIterator.hasNext()) {
+ complete();
return;
}
String event = activeIterator.next();
@@ -139,6 +139,18 @@ private void run() {
}
}
subscriber.onNext(event);
+ if (isCancelled()) {
+ return;
+ }
+ if (activeIterator.isExhausted()) {
+ complete();
+ return;
+ }
+ // Look ahead once so a finite stream can complete when demand ends on its last event.
+ if (!activeIterator.hasNext()) {
+ complete();
+ return;
+ }
}
} catch (Throwable exception) {
signalError(exception);
diff --git a/core/src/main/java/dev/frontal/sdk/models/ValidationException.java b/core/src/main/java/dev/frontal/sdk/models/ValidationException.java
index 85be29e..321dec4 100644
--- a/core/src/main/java/dev/frontal/sdk/models/ValidationException.java
+++ b/core/src/main/java/dev/frontal/sdk/models/ValidationException.java
@@ -6,6 +6,25 @@
public final class ValidationException extends FrontalException {
public ValidationException(
@Nullable String code, @Nullable String message, @Nullable String requestId, int statusCode) {
- super(code, message, requestId, statusCode, false);
+ this(code, message, requestId, statusCode, null);
+ }
+
+ public ValidationException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ @Nullable String responseBody) {
+ this(code, message, requestId, statusCode, responseBody, false);
+ }
+
+ public ValidationException(
+ @Nullable String code,
+ @Nullable String message,
+ @Nullable String requestId,
+ int statusCode,
+ @Nullable String responseBody,
+ boolean responseBodyTruncated) {
+ super(code, message, requestId, statusCode, false, null, responseBody, responseBodyTruncated);
}
}
diff --git a/core/src/main/java/dev/frontal/sdk/utils/Poller.java b/core/src/main/java/dev/frontal/sdk/utils/Poller.java
index 72fd92e..e693a4c 100644
--- a/core/src/main/java/dev/frontal/sdk/utils/Poller.java
+++ b/core/src/main/java/dev/frontal/sdk/utils/Poller.java
@@ -1,8 +1,8 @@
package dev.frontal.sdk;
+import java.io.IOException;
import java.time.Duration;
import java.util.Objects;
-import java.util.concurrent.Callable;
import java.util.concurrent.TimeoutException;
import java.util.function.Predicate;
@@ -10,15 +10,16 @@
public final class Poller {
private Poller() {}
- public static T pollUntil(Callable operation, Predicate finished, Duration interval, Duration timeout)
- throws Exception {
+ public static T pollUntil(
+ PollOperation operation, Predicate finished, Duration interval, Duration timeout)
+ throws IOException, InterruptedException, TimeoutException {
Objects.requireNonNull(operation, "operation");
Objects.requireNonNull(finished, "finished");
requirePositive(interval, "interval");
requirePositive(timeout, "timeout");
long deadline = System.nanoTime() + timeout.toNanos();
while (true) {
- T result = operation.call();
+ T result = operation.poll();
if (finished.test(result)) {
return result;
}
@@ -33,6 +34,11 @@ public static T pollUntil(Callable operation, Predicate finished, Dura
}
}
+ @FunctionalInterface
+ public interface PollOperation {
+ T poll() throws IOException, InterruptedException;
+ }
+
private static void requirePositive(Duration duration, String name) {
Objects.requireNonNull(duration, name);
if (duration.isZero() || duration.isNegative()) {
diff --git a/core/src/main/java/dev/frontal/sdk/utils/RequestUriBuilder.java b/core/src/main/java/dev/frontal/sdk/utils/RequestUriBuilder.java
index 2cf4cb7..bdde3aa 100644
--- a/core/src/main/java/dev/frontal/sdk/utils/RequestUriBuilder.java
+++ b/core/src/main/java/dev/frontal/sdk/utils/RequestUriBuilder.java
@@ -5,16 +5,16 @@
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
-import java.util.Map;
import java.util.Objects;
/** Builds request URIs and encodes path and query values as UTF-8. */
public final class RequestUriBuilder {
private RequestUriBuilder() {}
- public static URI build(URI baseUrl, Endpoint endpoint, List pathParameters, Map query) {
+ public static URI build(URI baseUrl, Endpoint endpoint, List pathParameters, QueryParams query) {
Objects.requireNonNull(baseUrl, "baseUrl");
Objects.requireNonNull(endpoint, "endpoint");
+ Objects.requireNonNull(query, "query");
List parameters = pathParameters == null ? List.of() : pathParameters;
if (parameters.size() != endpoint.pathParameterCount()) {
throw new IllegalArgumentException(
@@ -57,44 +57,23 @@ public static String encodePathSegment(String value) {
.replace("%7E", "~");
}
- private static String encodeQuery(Map query) {
- if (query == null || query.isEmpty()) {
+ private static String encodeQuery(QueryParams query) {
+ if (query.values().isEmpty()) {
return "";
}
List pairs = new ArrayList<>();
- query.forEach((name, value) -> {
- if (name == null || value == null) {
- return;
- }
- String wireName = toSnakeCase(name);
- if (value instanceof Iterable> values) {
- values.forEach(item -> addPair(pairs, wireName, item));
- } else if (value.getClass().isArray()) {
- int length = java.lang.reflect.Array.getLength(value);
- for (int index = 0; index < length; index++) {
- addPair(pairs, wireName, java.lang.reflect.Array.get(value, index));
- }
- } else {
- addPair(pairs, wireName, value);
- }
- });
+ query.values().forEach((name, values) -> values.forEach(value -> addPair(pairs, name, value)));
return String.join("&", pairs);
}
- private static void addPair(List pairs, String name, Object value) {
- if (value != null) {
- pairs.add(encodeQueryComponent(name) + "=" + encodeQueryComponent(value.toString()));
- }
+ private static void addPair(List pairs, String name, String value) {
+ pairs.add(encodeQueryComponent(name) + "=" + encodeQueryComponent(value));
}
private static String encodeQueryComponent(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20");
}
- private static String toSnakeCase(String value) {
- return value.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toLowerCase(java.util.Locale.ROOT);
- }
-
private static String trimTrailingSlash(String value) {
int end = value.length();
while (end > 0 && value.charAt(end - 1) == '/') {
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 241b25d..c12d7a2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,6 +1,6 @@
# Java SDK architecture
-The SDK is a Gradle multi-module project with one public artifact, `dev.frontal:frontal-sdk:1.0.0`, and one Java package, `dev.frontal.sdk`.
+The SDK is a Gradle multi-module project with one public artifact, `dev.frontal:frontal-sdk:2.0.0`, and one Java package, `dev.frontal.sdk`.
## Modules and source organization
@@ -10,14 +10,14 @@ The SDK is a Gradle multi-module project with one public artifact, `dev.frontal:
- `examples/` verifies the consumer experience with MockWebServer.
- Production classes remain in `dev.frontal.sdk`. The `api/`, `auth/`, `config/`, `models/`, `resources/`, and `utils/` folders organize types by role and do not create Java subpackages.
-`Endpoints` is derived from `contracts/sdk-endpoints.json`. The OpenAPI snapshots remain unchanged and feed the contract gate.
+`Endpoints`, nested resource clients, and concise operations are derived from `contracts/sdk-endpoints.json` and operation metadata in the committed OpenAPI snapshots. The snapshots remain unchanged and feed the contract gate. Resource clients follow route segments and expose conventional `list`, `get`, `create`, `update`, and `delete` methods plus named actions. Calls can omit `QueryParams` when they do not need query values. Request bodies without a usable schema use `JsonNode`, and callers choose response types where no model is available.
## Request flow
`Application → Frontal → service client → shared ApiClient → auth/config/retry → OkHttp → Frontal API`
-`Frontal` creates one `ApiClient` and shares it with each service client. `ClientConfig` is immutable after build. Each request gets a unique request ID, and error mapping happens once in the shared transport. Safe GET requests may retry; writes run once. Streaming endpoints transfer response-body ownership to `ApiStream`, `SseEventIterator`, or a Flow subscription so cancellation closes the connection.
+`Frontal` creates one `ApiClient` and shares it with each typed service client. `ClientConfig` is immutable after build. Each request gets a unique request ID, and error mapping happens once in the shared transport. Safe GET requests may retry; writes run once. Buffered responses are bounded by `maxResponseBytes`; error diagnostics have a separate `maxErrorBodyBytes` cap. `streamBody()` supports larger downloads without buffering. Streaming endpoints transfer response-body ownership to `ApiStream`, `SseEventIterator`, or a Flow subscription so cancellation closes the connection. SSE connections disable read and call timeouts; the caller must close or cancel long-lived streams.
## Service APIs
-AI, agents, and workflows have named convenience methods for their core operations. All 622 catalogued routes remain accessible through service-scoped `request` methods and the `Endpoints` constants. The contract gate maps every operation in the public and AI OpenAPI snapshots to an endpoint. Caller-provided classes, `TypeReference`, or Jackson `JsonNode` types handle payloads that the current snapshots do not fully model.
+The route inventory generates endpoint constants and named methods for the SDK’s 611 supported routes. Agent runs live under `agents().runs()`, while other nested paths follow their route resources. The contract gate verifies SDK routes against the committed inventory and maps supported operations in the public and AI OpenAPI snapshots. Caller-provided classes, `TypeReference`, or Jackson `JsonNode` types handle payloads that the current snapshots do not fully model. Generated references for service and resource clients live in `docs/api/`.
diff --git a/docs/ENTERPRISE_READINESS.md b/docs/ENTERPRISE_READINESS.md
index 5fc3cc3..f26950a 100644
--- a/docs/ENTERPRISE_READINESS.md
+++ b/docs/ENTERPRISE_READINESS.md
@@ -8,11 +8,12 @@ This page summarizes the controls in the Java SDK and the work required before a
- Shared OkHttp transport with bounded responses, request IDs, safe-read retries, and typed errors.
- MockWebServer coverage for request handling, retries, pagination, error mapping, and SSE streams.
- Contract checks that map all public and AI OpenAPI operations to Java endpoints.
+- Generated named operation methods and per-service references for supported routes. Agent run lookup is grouped under agents.
- Central Portal release workflow with GPG signing required for publication.
## Remaining release work
- Configure Central Portal and GPG credentials as protected GitHub secrets.
- Complete a security review of transport, credential handling, and logging.
-- Add operation-specific request and response models where the contracts define complete schemas.
+- Add operation-specific request and response models as upstream contracts provide complete schemas.
- Configure dependency scanning and release provenance for the repository.
diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md
index 556247c..833fbfa 100644
--- a/docs/ONBOARDING.md
+++ b/docs/ONBOARDING.md
@@ -4,7 +4,7 @@
2. Clone the repository and use the checked-in Gradle wrapper.
3. Run `./gradlew spotlessCheck assemble lint test examplesTest docsTest checkContracts`.
4. Review `AGENTS.md`, `docs/ARCHITECTURE.md`, and `contracts/README.md`.
-5. Select a route from `Endpoints` and compare it with `contracts/sdk-endpoints.json` and the applicable OpenAPI snapshot.
-6. Build a client with `Frontal.builder().apiKey(...).build()` and use the matching service accessor.
+5. Browse `docs/api/README.md` for the named method, then compare its route with `contracts/sdk-endpoints.json` and the applicable OpenAPI snapshot.
+6. Build a client with `Frontal.builder().apiKey(...).build()` and use the matching named service operation.
Export `FRONTAL_API_KEY` and optional settings into the process environment. Java does not load `.env` files automatically. Tests use MockWebServer and do not need live credentials.
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index 561696d..e9faaa6 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -1,5 +1,5 @@
# Java SDK overview
-The Frontal Java SDK is configured to publish the `dev.frontal:frontal-sdk:1.0.0` facade artifact from a Gradle multi-module build. Production sources use the single package `dev.frontal.sdk` and six role folders across `core`, `services`, and `sdk`.
+The Frontal Java SDK is configured to publish the `dev.frontal:frontal-sdk:2.0.0` facade artifact from a Gradle multi-module build. Production sources use the single package `dev.frontal.sdk` and six role folders across `core`, `services`, and `sdk`.
-The route inventory generates `Endpoints` constants for all 622 current API routes and maps every operation in the public and AI OpenAPI snapshots. `Frontal` creates service-scoped clients, and `ApiClient` handles Jackson JSON, binary payloads, multipart uploads, SSE streams, retries for safe reads, and structured HTTP errors. Request and response classes can be provided by SDK consumers where the shared contract snapshots do not include a typed schema.
+The SDK exposes 611 named operations across its service clients, with agent run lookup available through `frontal.agents()`. `Endpoints` constants follow the supported SDK route catalog. `ApiClient` handles Jackson JSON, binary payloads, multipart uploads, SSE streams, safe-read retries, bounded error diagnostics, and structured HTTP errors. Named operations use immutable `QueryParams`, `JsonNode` for request bodies without contract schemas, and caller-provided response types.
diff --git a/docs/README.md b/docs/README.md
index a2018ce..fd99a1d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,3 +1,3 @@
# Java documentation
-Read `OVERVIEW.md` for the SDK surface, `ARCHITECTURE.md` for the module and request flow, and `ONBOARDING.md` to set up the toolchain. Use `TESTING.md` for verification and `PUBLISHING.md` for release steps.
+Read `OVERVIEW.md` for the SDK surface, `ARCHITECTURE.md` for the module and request flow, and `ONBOARDING.md` to set up the toolchain. Browse [the service API reference](./api/README.md) for the generated operation catalog. See the root README for pagination, error handling, streaming, and serialization examples. Use `TESTING.md` for verification and `PUBLISHING.md` for release steps.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index ab5a67c..ec7d712 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -6,4 +6,4 @@
- [x] Implement service-scoped clients and accessors for the contract inventory.
- [x] Add endpoint generation and Java usage examples.
- [x] Expand transport tests and contract conformance reporting.
-- [x] Configure signed Central Portal release automation for version 1.0.0.
+- [x] Configure signed Central Portal release automation.
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 0000000..8e9215f
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,31 @@
+# Service API reference
+
+Generated from the committed route catalog for SDK service clients.
+
+Call-shaped listing of every operation: [methods as code](./methods-as-code.md).
+
+| Service | Routes | Reference |
+| --- | ---: | --- |
+| agents | 14 | [agents](./agents.md) |
+| ai | 9 | [ai](./ai.md) |
+| audit | 4 | [audit](./audit.md) |
+| auth | 66 | [auth](./auth.md) |
+| billing | 23 | [billing](./billing.md) |
+| blob | 8 | [blob](./blob.md) |
+| connection-tests | 1 | [connection-tests](./connection-tests.md) |
+| connectors | 12 | [connectors](./connectors.md) |
+| data | 151 | [data](./data.md) |
+| events | 17 | [events](./events.md) |
+| governance | 24 | [governance](./governance.md) |
+| invocations | 1 | [invocations](./invocations.md) |
+| lineage | 7 | [lineage](./lineage.md) |
+| observability | 31 | [observability](./observability.md) |
+| ontology | 171 | [ontology](./ontology.md) |
+| pipelines | 11 | [pipelines](./pipelines.md) |
+| providers | 1 | [providers](./providers.md) |
+| react | 0 | [react](./react.md) |
+| sandbox | 3 | [sandbox](./sandbox.md) |
+| schedules | 10 | [schedules](./schedules.md) |
+| webhook-endpoints | 7 | [webhook-endpoints](./webhook-endpoints.md) |
+| webhooks | 10 | [webhooks](./webhooks.md) |
+| workflows | 30 | [workflows](./workflows.md) |
diff --git a/docs/api/agents.md b/docs/api/agents.md
new file mode 100644
index 0000000..314cafa
--- /dev/null
+++ b/docs/api/agents.md
@@ -0,0 +1,66 @@
+# Agents API
+
+Service accessor: `frontal.agents()` (`AgentsServiceClient`).
+
+Operations are grouped by resource path. Collection methods use `list` and `create`; item methods use `get`, `update`, and `delete`. Calls can omit `QueryParams` when no query values are needed. Use contract-defined `JsonNode` bodies and caller-selected response types where schemas are not available.
+
+| Method | HTTP | Route | Parameters | Response |
+| --- | --- | --- | --- | --- |
+| `agents().delete(...)` | `DELETE` | `/agents/{param}` | `String agentId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().delete(...)` | `DELETE` | `/agents/{param}` | `String agentId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().delete(...)` | `DELETE` | `/agents/{param}` | `String agentId, Class responseType` | `@Nullable T` |
+| `agents().delete(...)` | `DELETE` | `/agents/{param}` | `String agentId, TypeReference responseType` | `@Nullable T` |
+| `agents().list(...)` | `GET` | `/agents` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().list(...)` | `GET` | `/agents` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().list(...)` | `GET` | `/agents` | `Class responseType` | `@Nullable T` |
+| `agents().list(...)` | `GET` | `/agents` | `TypeReference responseType` | `@Nullable T` |
+| `agents().health(...)` | `GET` | `/agents/health` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().health(...)` | `GET` | `/agents/health` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().health(...)` | `GET` | `/agents/health` | `Class responseType` | `@Nullable T` |
+| `agents().health(...)` | `GET` | `/agents/health` | `TypeReference responseType` | `@Nullable T` |
+| `agents().get(...)` | `GET` | `/agents/{param}` | `String agentId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().get(...)` | `GET` | `/agents/{param}` | `String agentId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().get(...)` | `GET` | `/agents/{param}` | `String agentId, Class responseType` | `@Nullable T` |
+| `agents().get(...)` | `GET` | `/agents/{param}` | `String agentId, TypeReference responseType` | `@Nullable T` |
+| `agents().create(...)` | `POST` | `/agents` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().create(...)` | `POST` | `/agents` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().create(...)` | `POST` | `/agents` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().create(...)` | `POST` | `/agents` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().rollback(...)` | `POST` | `/agents/{param}/rollback` | `String agentId, QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().rollback(...)` | `POST` | `/agents/{param}/rollback` | `String agentId, QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().rollback(...)` | `POST` | `/agents/{param}/rollback` | `String agentId, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().rollback(...)` | `POST` | `/agents/{param}/rollback` | `String agentId, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().update(...)` | `PUT` | `/agents/{param}` | `String agentId, QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().update(...)` | `PUT` | `/agents/{param}` | `String agentId, QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().update(...)` | `PUT` | `/agents/{param}` | `String agentId, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().update(...)` | `PUT` | `/agents/{param}` | `String agentId, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().getByActionRunId(...)` | `GET` | `/action-runs/{param}` | `String actionRunId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().runs().getByActionRunId(...)` | `GET` | `/action-runs/{param}` | `String actionRunId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().getByActionRunId(...)` | `GET` | `/action-runs/{param}` | `String actionRunId, Class responseType` | `@Nullable T` |
+| `agents().runs().getByActionRunId(...)` | `GET` | `/action-runs/{param}` | `String actionRunId, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().get(...)` | `GET` | `/agents/runs/{param}` | `String runId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().runs().get(...)` | `GET` | `/agents/runs/{param}` | `String runId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().get(...)` | `GET` | `/agents/runs/{param}` | `String runId, Class responseType` | `@Nullable T` |
+| `agents().runs().get(...)` | `GET` | `/agents/runs/{param}` | `String runId, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().conversation(...)` | `GET` | `/agents/runs/{param}/conversation` | `String runId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().runs().conversation(...)` | `GET` | `/agents/runs/{param}/conversation` | `String runId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().conversation(...)` | `GET` | `/agents/runs/{param}/conversation` | `String runId, Class responseType` | `@Nullable T` |
+| `agents().runs().conversation(...)` | `GET` | `/agents/runs/{param}/conversation` | `String runId, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().list(...)` | `GET` | `/agents/{param}/runs` | `String agentId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().runs().list(...)` | `GET` | `/agents/{param}/runs` | `String agentId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().list(...)` | `GET` | `/agents/{param}/runs` | `String agentId, Class responseType` | `@Nullable T` |
+| `agents().runs().list(...)` | `GET` | `/agents/{param}/runs` | `String agentId, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().create(...)` | `POST` | `/agents/{param}/runs` | `String agentId, QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().runs().create(...)` | `POST` | `/agents/{param}/runs` | `String agentId, QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().create(...)` | `POST` | `/agents/{param}/runs` | `String agentId, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `agents().runs().create(...)` | `POST` | `/agents/{param}/runs` | `String agentId, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `agents().runs().stream(...)` | `STREAM` | `/agents/runs/{param}/stream` | `String runId, QueryParams query` | `Flow.Publisher` |
+| `agents().runs().stream(...)` | `STREAM` | `/agents/runs/{param}/stream` | `String runId` | `Flow.Publisher` |
+| `agents().runs().streamBlocking(...)` | `STREAM` | `/agents/runs/{param}/stream` | `String runId, QueryParams query` | `SseEventIterator` |
+| `agents().runs().streamBlocking(...)` | `STREAM` | `/agents/runs/{param}/stream` | `String runId` | `SseEventIterator` |
+| `agents().versions().list(...)` | `GET` | `/agents/{param}/versions` | `String agentId, QueryParams query, Class responseType` | `@Nullable T` |
+| `agents().versions().list(...)` | `GET` | `/agents/{param}/versions` | `String agentId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `agents().versions().list(...)` | `GET` | `/agents/{param}/versions` | `String agentId, Class responseType` | `@Nullable T` |
+| `agents().versions().list(...)` | `GET` | `/agents/{param}/versions` | `String agentId, TypeReference responseType` | `@Nullable T` |
+
+The generic `request(...)` methods and `Endpoints` constants remain available.
diff --git a/docs/api/ai.md b/docs/api/ai.md
new file mode 100644
index 0000000..8213353
--- /dev/null
+++ b/docs/api/ai.md
@@ -0,0 +1,46 @@
+# Ai API
+
+Service accessor: `frontal.ai()` (`AiServiceClient`).
+
+Operations are grouped by resource path. Collection methods use `list` and `create`; item methods use `get`, `update`, and `delete`. Calls can omit `QueryParams` when no query values are needed. Use contract-defined `JsonNode` bodies and caller-selected response types where schemas are not available.
+
+| Method | HTTP | Route | Parameters | Response |
+| --- | --- | --- | --- | --- |
+| `ai().health(...)` | `GET` | `/health` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `ai().health(...)` | `GET` | `/health` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `ai().health(...)` | `GET` | `/health` | `Class responseType` | `@Nullable T` |
+| `ai().health(...)` | `GET` | `/health` | `TypeReference responseType` | `@Nullable T` |
+| `ai().internal().embed(...)` | `POST` | `/internal/embeddings` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().embed(...)` | `POST` | `/internal/embeddings` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().embed(...)` | `POST` | `/internal/embeddings` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().embed(...)` | `POST` | `/internal/embeddings` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predict(...)` | `POST` | `/internal/predictions` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().predict(...)` | `POST` | `/internal/predictions` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predict(...)` | `POST` | `/internal/predictions` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().predict(...)` | `POST` | `/internal/predictions` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().rerank(...)` | `POST` | `/internal/rerank` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().rerank(...)` | `POST` | `/internal/rerank` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().rerank(...)` | `POST` | `/internal/rerank` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().internal().rerank(...)` | `POST` | `/internal/rerank` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predictForm(...)` | `POSTFORMDATA` | `/internal/predictions` | `QueryParams query, Map fields, Map files, Class responseType` | `@Nullable T` |
+| `ai().internal().predictForm(...)` | `POSTFORMDATA` | `/internal/predictions` | `QueryParams query, Map fields, Map files, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predictForm(...)` | `POSTFORMDATA` | `/internal/predictions` | `Map fields, Map files, Class responseType` | `@Nullable T` |
+| `ai().internal().predictForm(...)` | `POSTFORMDATA` | `/internal/predictions` | `Map fields, Map files, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predictRaw(...)` | `POSTRAW` | `/internal/predictions` | `QueryParams query, byte[] body, Class responseType` | `@Nullable T` |
+| `ai().internal().predictRaw(...)` | `POSTRAW` | `/internal/predictions` | `QueryParams query, byte[] body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().predictRaw(...)` | `POSTRAW` | `/internal/predictions` | `byte[] body, Class responseType` | `@Nullable T` |
+| `ai().internal().predictRaw(...)` | `POSTRAW` | `/internal/predictions` | `byte[] body, TypeReference responseType` | `@Nullable T` |
+| `ai().chat().completions().create(...)` | `POST` | `/ai/chat/completions` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().chat().completions().create(...)` | `POST` | `/ai/chat/completions` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().chat().completions().create(...)` | `POST` | `/ai/chat/completions` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `ai().chat().completions().create(...)` | `POST` | `/ai/chat/completions` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().models().list(...)` | `GET` | `/internal/models` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `ai().internal().models().list(...)` | `GET` | `/internal/models` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().models().list(...)` | `GET` | `/internal/models` | `Class responseType` | `@Nullable T` |
+| `ai().internal().models().list(...)` | `GET` | `/internal/models` | `TypeReference responseType` | `@Nullable T` |
+| `ai().internal().models().defaults(...)` | `GET` | `/internal/models/defaults` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `ai().internal().models().defaults(...)` | `GET` | `/internal/models/defaults` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `ai().internal().models().defaults(...)` | `GET` | `/internal/models/defaults` | `Class responseType` | `@Nullable T` |
+| `ai().internal().models().defaults(...)` | `GET` | `/internal/models/defaults` | `TypeReference responseType` | `@Nullable T` |
+
+The generic `request(...)` methods and `Endpoints` constants remain available.
diff --git a/docs/api/audit.md b/docs/api/audit.md
new file mode 100644
index 0000000..3a8584b
--- /dev/null
+++ b/docs/api/audit.md
@@ -0,0 +1,26 @@
+# Audit API
+
+Service accessor: `frontal.audit()` (`AuditClient`).
+
+Operations are grouped by resource path. Collection methods use `list` and `create`; item methods use `get`, `update`, and `delete`. Calls can omit `QueryParams` when no query values are needed. Use contract-defined `JsonNode` bodies and caller-selected response types where schemas are not available.
+
+| Method | HTTP | Route | Parameters | Response |
+| --- | --- | --- | --- | --- |
+| `audit().events().list(...)` | `GET` | `/audit/events` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `audit().events().list(...)` | `GET` | `/audit/events` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `audit().events().list(...)` | `GET` | `/audit/events` | `Class responseType` | `@Nullable T` |
+| `audit().events().list(...)` | `GET` | `/audit/events` | `TypeReference responseType` | `@Nullable T` |
+| `audit().events().get(...)` | `GET` | `/audit/events/{param}` | `String eventId, QueryParams query, Class responseType` | `@Nullable T` |
+| `audit().events().get(...)` | `GET` | `/audit/events/{param}` | `String eventId, QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `audit().events().get(...)` | `GET` | `/audit/events/{param}` | `String eventId, Class responseType` | `@Nullable T` |
+| `audit().events().get(...)` | `GET` | `/audit/events/{param}` | `String eventId, TypeReference responseType` | `@Nullable T` |
+| `audit().events().create(...)` | `POST` | `/audit/events` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `audit().events().create(...)` | `POST` | `/audit/events` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `audit().events().create(...)` | `POST` | `/audit/events` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `audit().events().create(...)` | `POST` | `/audit/events` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `audit().events().batch(...)` | `POST` | `/audit/events/batch` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `audit().events().batch(...)` | `POST` | `/audit/events/batch` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `audit().events().batch(...)` | `POST` | `/audit/events/batch` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `audit().events().batch(...)` | `POST` | `/audit/events/batch` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+
+The generic `request(...)` methods and `Endpoints` constants remain available.
diff --git a/docs/api/auth.md b/docs/api/auth.md
new file mode 100644
index 0000000..bf9e443
--- /dev/null
+++ b/docs/api/auth.md
@@ -0,0 +1,274 @@
+# Auth API
+
+Service accessor: `frontal.auth()` (`AuthClient`).
+
+Operations are grouped by resource path. Collection methods use `list` and `create`; item methods use `get`, `update`, and `delete`. Calls can omit `QueryParams` when no query values are needed. Use contract-defined `JsonNode` bodies and caller-selected response types where schemas are not available.
+
+| Method | HTTP | Route | Parameters | Response |
+| --- | --- | --- | --- | --- |
+| `auth().getUser(...)` | `GET` | `/auth/user` | `QueryParams query, Class responseType` | `@Nullable T` |
+| `auth().getUser(...)` | `GET` | `/auth/user` | `QueryParams query, TypeReference responseType` | `@Nullable T` |
+| `auth().getUser(...)` | `GET` | `/auth/user` | `Class responseType` | `@Nullable T` |
+| `auth().getUser(...)` | `GET` | `/auth/user` | `TypeReference responseType` | `@Nullable T` |
+| `auth().createAuthorize(...)` | `POST` | `/auth/authorize` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createAuthorize(...)` | `POST` | `/auth/authorize` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createAuthorize(...)` | `POST` | `/auth/authorize` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createAuthorize(...)` | `POST` | `/auth/authorize` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createInvite(...)` | `POST` | `/auth/invite` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createInvite(...)` | `POST` | `/auth/invite` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createInvite(...)` | `POST` | `/auth/invite` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createInvite(...)` | `POST` | `/auth/invite` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().login(...)` | `POST` | `/auth/login` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().login(...)` | `POST` | `/auth/login` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().login(...)` | `POST` | `/auth/login` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().login(...)` | `POST` | `/auth/login` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().logout(...)` | `POST` | `/auth/logout` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().logout(...)` | `POST` | `/auth/logout` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().logout(...)` | `POST` | `/auth/logout` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().logout(...)` | `POST` | `/auth/logout` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createOtp(...)` | `POST` | `/auth/otp` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createOtp(...)` | `POST` | `/auth/otp` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createOtp(...)` | `POST` | `/auth/otp` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createOtp(...)` | `POST` | `/auth/otp` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createReauthenticate(...)` | `POST` | `/auth/reauthenticate` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createReauthenticate(...)` | `POST` | `/auth/reauthenticate` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createReauthenticate(...)` | `POST` | `/auth/reauthenticate` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createReauthenticate(...)` | `POST` | `/auth/reauthenticate` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createRecover(...)` | `POST` | `/auth/recover` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createRecover(...)` | `POST` | `/auth/recover` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createRecover(...)` | `POST` | `/auth/recover` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createRecover(...)` | `POST` | `/auth/recover` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createResend(...)` | `POST` | `/auth/resend` | `QueryParams query, @Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createResend(...)` | `POST` | `/auth/resend` | `QueryParams query, @Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createResend(...)` | `POST` | `/auth/resend` | `@Nullable JsonNode body, Class responseType` | `@Nullable T` |
+| `auth().createResend(...)` | `POST` | `/auth/resend` | `@Nullable JsonNode body, TypeReference responseType` | `@Nullable T` |
+| `auth().createSignup(...)` | `POST` | `/auth/signup` | `QueryParams query, @Nullable JsonNode body, Class