Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,7 @@
*.class
/out/
/coverage/

# Python cache files
__pycache__/
*.py[cod]
2 changes: 1 addition & 1 deletion .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
".": "1.0.0"
".": "2.0.0"
}
14 changes: 6 additions & 8 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
66 changes: 59 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,87 @@ Maven:
<dependency>
<groupId>dev.frontal</groupId>
<artifactId>frontal-sdk</artifactId>
<version>1.0.0</version>
<version>2.0.0</version>
</dependency>
```

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<T>` 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<T>` with `nextPage()`, `all()`, and `Iterable<T>` support. Streaming endpoints expose `Flow.Publisher<String>` 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.
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
9 changes: 5 additions & 4 deletions contracts/reports/conformance.json
Original file line number Diff line number Diff line change
@@ -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."
}
11 changes: 6 additions & 5 deletions contracts/reports/migration-matrix.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading