release: 0.1.0-alpha.6

.github/workflows/ci.yml

@@ -1,12 +1,14 @@
 name: CI
 on:
   push:
-    branches-ignore:
-      - 'generated'
-      - 'codegen/**'
-      - 'integrated/**'
-      - 'stl-preview-head/**'
-      - 'stl-preview-base/**'
+    branches:
+      - '**'
+      - '!integrated/**'
+      - '!stl-preview-head/**'
+      - '!stl-preview-base/**'
+      - '!generated'
+      - '!codegen/**'
+      - 'codegen/stl/**'
   pull_request:
     branches-ignore:
       - 'stl-preview-head/**'
@@ -17,7 +19,7 @@ jobs:
     timeout-minutes: 15
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/arcade-engine-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
 
     steps:
       - uses: actions/checkout@v6
@@ -44,7 +46,7 @@ jobs:
       contents: read
       id-token: write
     runs-on: ${{ github.repository == 'stainless-sdks/arcade-engine-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
 
     steps:
       - uses: actions/checkout@v6

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 .gradle
 .idea
 .kotlin

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.5"
+  ".": "0.1.0-alpha.6"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/arcade-ai%2Farcade-engine-6ff494eafa2c154892716407682bb2296cff4f18c45765c5fb16bdf36f452ae1.yml
-openapi_spec_hash: 63dde2481a7d51042a241bfba232b0b0
-config_hash: bf64816643634a621cd0ffd93d9c4347
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/arcade-ai/arcade-engine-22ce2a59bb1f308059c59ed19600698c5562a62c75f15c85429d186e9d8bdde6.yml
+openapi_spec_hash: 2923fbda6c2899ade719d00540c34ff6
+config_hash: 2d4163acdeacd75903f978cd79c35d14

CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.1.0-alpha.6 (2026-05-05)
+
+Full Changelog: [v0.1.0-alpha.5...v0.1.0-alpha.6](https://github.com/ArcadeAI/arcade-java/compare/v0.1.0-alpha.5...v0.1.0-alpha.6)
+
+### Features
+
+* **api:** api update ([aa56504](https://github.com/ArcadeAI/arcade-java/commit/aa565048f02eb4a21657d4e51c4975376968b579))
+* **api:** api update ([f7f972b](https://github.com/ArcadeAI/arcade-java/commit/f7f972bc274de10da54ffe2004d9d50fa16bc5a3))
+* **api:** api update ([acfd5b0](https://github.com/ArcadeAI/arcade-java/commit/acfd5b0aedbb445e1269a6b879111ff19c8aeef5))
+* **api:** api update ([5871f8b](https://github.com/ArcadeAI/arcade-java/commit/5871f8b7d0a2a89a6cbb57561a292b32381c74b6))
+* **client:** more robust error parsing ([1043b59](https://github.com/ArcadeAI/arcade-java/commit/1043b591c5cee640130803058086ab444bd07b58))
+* support setting headers via env ([219088d](https://github.com/ArcadeAI/arcade-java/commit/219088d6cdc541d7ae57d36a438f2e6b8894f106))
+
+
+### Bug Fixes
+
+* **client:** allow updating header/query affecting fields in `toBuilder()` ([f86e1f2](https://github.com/ArcadeAI/arcade-java/commit/f86e1f2dff33a369dd6d52119ce670747dfd2392))
+
+
+### Performance Improvements
+
+* **client:** create one json mapper ([be74413](https://github.com/ArcadeAI/arcade-java/commit/be744132658d4afa95b3d42edc256a3d245a931a))
+
+
+### Chores
+
+* **ci:** skip lint on metadata-only changes ([d5942be](https://github.com/ArcadeAI/arcade-java/commit/d5942be3ea63057a3267602dc72046e71d9a5855))
+* **internal:** bump ktfmt ([f38504b](https://github.com/ArcadeAI/arcade-java/commit/f38504b554f72ac9f701716ff1ad40ec5f1a47b2))
+* **internal:** codegen related update ([317c328](https://github.com/ArcadeAI/arcade-java/commit/317c328ecaf054e2fbdea4b6dbfb3a1451bb5070))
+* **internal:** tweak CI branches ([5213191](https://github.com/ArcadeAI/arcade-java/commit/521319108a7b064979e96ecf2fff5e74681b56bf))
+* **internal:** update gitignore ([c9b3d8f](https://github.com/ArcadeAI/arcade-java/commit/c9b3d8f8b7825876526e6dca16859c9f12fcce37))
+* **internal:** update multipart form array serialization ([abeec96](https://github.com/ArcadeAI/arcade-java/commit/abeec961730398bb0c49f01ea13312468be4787c))
+* **internal:** update retry delay tests ([993657b](https://github.com/ArcadeAI/arcade-java/commit/993657b3ac45eafee6b85f76a578f2c6daaacfe2))
+* remove duplicated dokka setup ([8e3a087](https://github.com/ArcadeAI/arcade-java/commit/8e3a087be33daae54aa87f67cdc62a22f566d504))
+* **tests:** bump steady to v0.19.4 ([0d022df](https://github.com/ArcadeAI/arcade-java/commit/0d022dfe027631ea83e1794bcb9e79824ab28f0f))
+* **tests:** bump steady to v0.19.5 ([d186f97](https://github.com/ArcadeAI/arcade-java/commit/d186f9769310ebff3584418642cc0b31a13e1d1c))
+* **tests:** bump steady to v0.19.6 ([b5094e5](https://github.com/ArcadeAI/arcade-java/commit/b5094e5507917137cf7b30c90e1028c122bd1331))
+* **tests:** bump steady to v0.19.7 ([231a1a7](https://github.com/ArcadeAI/arcade-java/commit/231a1a764782bb5bdcd1118630b3bbd544333aa4))
+* **tests:** bump steady to v0.20.1 ([b936990](https://github.com/ArcadeAI/arcade-java/commit/b93699052685356a902c34f38d8e46a617e77454))
+* **tests:** bump steady to v0.20.2 ([7dfba2e](https://github.com/ArcadeAI/arcade-java/commit/7dfba2ef15e2c5f6412a64f23cde8138159c42ea))
+* **tests:** bump steady to v0.22.1 ([bca6f99](https://github.com/ArcadeAI/arcade-java/commit/bca6f993c4876c486640b25ca1d41ff45f299263))
+
+
+### Documentation
+
+* clarify forwards compat behavior ([0053367](https://github.com/ArcadeAI/arcade-java/commit/00533674a82a9ec0815ef3d6cb12390927aa9cd2))
+
+
+### Refactors
+
+* **tests:** switch from prism to steady ([ae8ff34](https://github.com/ArcadeAI/arcade-java/commit/ae8ff343537d6ff24a3346fac27516c2bc3e07d9))
+
 ## 0.1.0-alpha.5 (2026-03-16)
 
 Full Changelog: [v0.1.0-alpha.4...v0.1.0-alpha.5](https://github.com/ArcadeAI/arcade-java/compare/v0.1.0-alpha.4...v0.1.0-alpha.5)

CONTRIBUTING.md

@@ -40,7 +40,7 @@ Most tests require you to [run a mock server](https://github.com/stoplightio/pri
 ./scripts/mock --daemon
 ```
 
-The mock serer will run in the background allowing you to run tests from the command line `./gradlew test` or from your IDE.
+The mock server will run in the background allowing you to run tests from the command line `./gradlew test` or from your IDE.
 
 To stop the mock server run:
 ```shell
@@ -62,3 +62,22 @@ To format and fix all issues automatically:
 ```sh
 $ ./scripts/format
 ```
+
+## Release and pull request process
+
+As mentioned above, most of the code in this repository is generated. So the pull requests process may different from what you are expecting. Here are the steps:
+
+- Custom code changes should target the `next` branch in [`ArcadeAI/arcade-java`](https://github.com/arcadeai/arcade-java).
+- Be selective on what you are changing, as this may cause [merge conflicts](https://www.stainless.com/docs/sdks/configure/custom-code) with the generated code.
+- Create a new pull request against `next`, CI will build and test it.
+- Once it is merged to `next`, and when there have been upstream changes to the OpenAPI spec, you will see a pull request titled "release: <version>" (where `<version>` is the next version to be released)
+- Review it, most of the changes will have been generated, make sure the changes from your pull request are included.
+- Approve the PR, and merge it.
+  - The `next` branch will be rebased to `main`, so you will need to rewrite the branch, something like: `git fetch origin next && git reset --hard origin/next`
+- Once changes are merged to `main` a CI job will deploy the version to [Maven Central](https://central.sonatype.com/search?q=arcade-java). There may be a delay between the time it is published until the time it shows up in the Maven Central search results.
+
+## Troubleshooting tips
+
+If you are running into issues deploying to Maven Central, run the [`Release Doctor`](https://github.com/ArcadeAI/arcade-java/actions/workflows/release-doctor.yml) CI job, this will check that the required environment variables are set correctly.
+
+The [`CI` workflow](https://github.com/ArcadeAI/arcade-java/blob/main/.github/workflows/ci.yml), includes a couple of `if` statments that look like: `github.repository == 'stainless-sdks/arcade-engine-java'`. These are ONLY used for pre-release builds when the Stainless SDK code is generated. These are NOT used currently (in the future if there are multiple Java project repositories, this Maven repository could be used to test nightly builds). Otherwise, [build from source](#building-the-repository-from-source).

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/dev.arcade/arcade-java)](https://central.sonatype.com/artifact/dev.arcade/arcade-java/0.1.0-alpha.5)
-[![javadoc](https://javadoc.io/badge2/dev.arcade/arcade-java/0.1.0-alpha.5/javadoc.svg)](https://javadoc.io/doc/dev.arcade/arcade-java/0.1.0-alpha.5)
+[![Maven Central](https://img.shields.io/maven-central/v/dev.arcade/arcade-java)](https://central.sonatype.com/artifact/dev.arcade/arcade-java/0.1.0-alpha.6)
+[![javadoc](https://javadoc.io/badge2/dev.arcade/arcade-java/0.1.0-alpha.6/javadoc.svg)](https://javadoc.io/doc/dev.arcade/arcade-java/0.1.0-alpha.6)
 
 <!-- x-release-please-end -->
 
@@ -13,7 +13,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [docs.arcade.dev](https://docs.arcade.dev). Javadocs are available on [javadoc.io](https://javadoc.io/doc/dev.arcade/arcade-java/0.1.0-alpha.5).
+The REST API documentation can be found on [docs.arcade.dev](https://docs.arcade.dev). Javadocs are available on [javadoc.io](https://javadoc.io/doc/dev.arcade/arcade-java/0.1.0-alpha.6).
 
 <!-- x-release-please-end -->
 
@@ -24,7 +24,7 @@ The REST API documentation can be found on [docs.arcade.dev](https://docs.arcade
 ### Gradle
 
 ```kotlin
-implementation("dev.arcade:arcade-java:0.1.0-alpha.5")
+implementation("dev.arcade:arcade-java:0.1.0-alpha.6")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("dev.arcade:arcade-java:0.1.0-alpha.5")
 <dependency>
   <groupId>dev.arcade</groupId>
   <artifactId>arcade-java</artifactId>
-  <version>0.1.0-alpha.5</version>
+  <version>0.1.0-alpha.6</version>
 </dependency>
 ```
 
@@ -50,7 +50,6 @@ import dev.arcade.client.ArcadeClient;
 import dev.arcade.client.okhttp.ArcadeOkHttpClient;
 import dev.arcade.models.tools.ExecuteToolRequest;
 import dev.arcade.models.tools.ExecuteToolResponse;
-import dev.arcade.models.tools.ToolExecuteParams;
 
 // Configures using the `arcade.apiKey` and `arcade.baseUrl` system properties
 // Or configures using the `ARCADE_API_KEY` and `ARCADE_BASE_URL` environment variables
@@ -186,7 +185,6 @@ import dev.arcade.client.ArcadeClient;
 import dev.arcade.client.okhttp.ArcadeOkHttpClient;
 import dev.arcade.models.tools.ExecuteToolRequest;
 import dev.arcade.models.tools.ExecuteToolResponse;
-import dev.arcade.models.tools.ToolExecuteParams;
 import java.util.concurrent.CompletableFuture;
 
 // Configures using the `arcade.apiKey` and `arcade.baseUrl` system properties
@@ -206,7 +204,6 @@ import dev.arcade.client.ArcadeClientAsync;
 import dev.arcade.client.okhttp.ArcadeOkHttpClientAsync;
 import dev.arcade.models.tools.ExecuteToolRequest;
 import dev.arcade.models.tools.ExecuteToolResponse;
-import dev.arcade.models.tools.ToolExecuteParams;
 import java.util.concurrent.CompletableFuture;
 
 // Configures using the `arcade.apiKey` and `arcade.baseUrl` system properties
@@ -232,7 +229,6 @@ import dev.arcade.core.http.Headers;
 import dev.arcade.core.http.HttpResponseFor;
 import dev.arcade.models.chat.ChatRequest;
 import dev.arcade.models.chat.ChatResponse;
-import dev.arcade.models.chat.completions.CompletionCreateParams;
 
 ChatRequest params = ChatRequest.builder().build();
 HttpResponseFor<ChatResponse> chatResponse = client.chat().completions().withRawResponse().create(params);
@@ -710,7 +706,9 @@ In rare cases, the API may return a response that doesn't match the expected typ
 
 By default, the SDK will not throw an exception in this case. It will throw [`ArcadeInvalidDataException`](arcade-java-core/src/main/kotlin/dev/arcade/errors/ArcadeInvalidDataException.kt) only if you directly access the property.
 
-If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
+Validating the response is _not_ forwards compatible with new types from the API for existing fields.
+
+If you would still prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 
 ```java
 import dev.arcade.models.tools.ExecuteToolResponse;

arcade-java-client-okhttp/src/main/kotlin/dev/arcade/client/okhttp/ArcadeOkHttpClient.kt

@@ -230,6 +230,9 @@ class ArcadeOkHttpClient private constructor() {
         /**
          * Whether to call `validate` on every response before returning it.
          *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
          * Defaults to false, which means the shape of the response will not be validated upfront.
          * Instead, validation will only occur for the parts of the response that are accessed.
          */

arcade-java-client-okhttp/src/main/kotlin/dev/arcade/client/okhttp/ArcadeOkHttpClientAsync.kt

@@ -230,6 +230,9 @@ class ArcadeOkHttpClientAsync private constructor() {
         /**
          * Whether to call `validate` on every response before returning it.
          *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
          * Defaults to false, which means the shape of the response will not be validated upfront.
          * Instead, validation will only occur for the parts of the response that are accessed.
          */

arcade-java-core/src/main/kotlin/dev/arcade/core/ClientOptions.kt

@@ -80,6 +80,9 @@ private constructor(
     /**
      * Whether to call `validate` on every response before returning it.
      *
+     * Setting this to `true` is _not_ forwards compatible with new types from the API for existing
+     * fields.
+     *
      * Defaults to false, which means the shape of the response will not be validated upfront.
      * Instead, validation will only occur for the parts of the response that are accessed.
      */
@@ -260,6 +263,9 @@ private constructor(
         /**
          * Whether to call `validate` on every response before returning it.
          *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
          * Defaults to false, which means the shape of the response will not be validated upfront.
          * Instead, validation will only occur for the parts of the response that are accessed.
          */
@@ -405,6 +411,14 @@ private constructor(
             (System.getProperty("arcade.apiKey") ?: System.getenv("ARCADE_API_KEY"))?.let {
                 apiKey(it)
             }
+            System.getenv("ARCADE_CUSTOM_HEADERS")?.let { customHeadersEnv ->
+                for (line in customHeadersEnv.split("\n")) {
+                    val colon = line.indexOf(':')
+                    if (colon >= 0) {
+                        putHeader(line.substring(0, colon).trim(), line.substring(colon + 1).trim())
+                    }
+                }
+            }
         }
 
         /**
@@ -453,13 +467,14 @@ private constructor(
             headers.put("X-Stainless-Runtime", "JRE")
             headers.put("X-Stainless-Runtime-Version", getJavaVersion())
             headers.put("X-Stainless-Kotlin-Version", KotlinVersion.CURRENT.toString())
+            // We replace after all the default headers to allow end-users to overwrite them.
+            headers.replaceAll(this.headers.build())
+            queryParams.replaceAll(this.queryParams.build())
             apiKey.let {
                 if (!it.isEmpty()) {
-                    headers.put("Authorization", it)
+                    headers.replace("Authorization", it)
                 }
             }
-            headers.replaceAll(this.headers.build())
-            queryParams.replaceAll(this.queryParams.build())
 
             return ClientOptions(
                 httpClient,

arcade-java-core/src/main/kotlin/dev/arcade/core/ObjectMappers.kt

@@ -29,7 +29,9 @@ import java.time.ZoneId
 import java.time.format.DateTimeFormatter
 import java.time.temporal.ChronoField
 
-fun jsonMapper(): JsonMapper =
+fun jsonMapper(): JsonMapper = JSON_MAPPER
+
+private val JSON_MAPPER: JsonMapper =
     JsonMapper.builder()
         .addModule(kotlinModule())
         .addModule(Jdk8Module())

arcade-java-core/src/main/kotlin/dev/arcade/core/RequestOptions.kt

@@ -33,6 +33,15 @@ class RequestOptions private constructor(val responseValidation: Boolean?, val t
         private var responseValidation: Boolean? = null
         private var timeout: Timeout? = null
 
+        /**
+         * Whether to call `validate` on the response before returning it.
+         *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
+         * Defaults to false, which means the shape of the response will not be validated upfront.
+         * Instead, validation will only occur for the parts of the response that are accessed.
+         */
         fun responseValidation(responseValidation: Boolean) = apply {
             this.responseValidation = responseValidation
         }

arcade-java-core/src/main/kotlin/dev/arcade/errors/BadRequestException.kt

@@ -5,12 +5,16 @@ package dev.arcade.errors
 import dev.arcade.core.JsonValue
 import dev.arcade.core.checkRequired
 import dev.arcade.core.http.Headers
+import dev.arcade.core.jsonMapper
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 class BadRequestException
 private constructor(private val headers: Headers, private val body: JsonValue, cause: Throwable?) :
-    ArcadeServiceException("400: $body", cause) {
+    ArcadeServiceException(
+        "400: ${if (body.isMissing()) "Unknown" else jsonMapper().writeValueAsString(body)}",
+        cause,
+    ) {
 
     override fun statusCode(): Int = 400
 

arcade-java-core/src/main/kotlin/dev/arcade/errors/InternalServerException.kt

@@ -5,6 +5,7 @@ package dev.arcade.errors
 import dev.arcade.core.JsonValue
 import dev.arcade.core.checkRequired
 import dev.arcade.core.http.Headers
+import dev.arcade.core.jsonMapper
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
@@ -14,7 +15,11 @@ private constructor(
     private val headers: Headers,
     private val body: JsonValue,
     cause: Throwable?,
-) : ArcadeServiceException("$statusCode: $body", cause) {
+) :
+    ArcadeServiceException(
+        "$statusCode: ${if (body.isMissing()) "Unknown" else jsonMapper().writeValueAsString(body)}",
+        cause,
+    ) {
 
     override fun statusCode(): Int = statusCode
 

arcade-java-core/src/main/kotlin/dev/arcade/errors/NotFoundException.kt

@@ -5,12 +5,16 @@ package dev.arcade.errors
 import dev.arcade.core.JsonValue
 import dev.arcade.core.checkRequired
 import dev.arcade.core.http.Headers
+import dev.arcade.core.jsonMapper
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 class NotFoundException
 private constructor(private val headers: Headers, private val body: JsonValue, cause: Throwable?) :
-    ArcadeServiceException("404: $body", cause) {
+    ArcadeServiceException(
+        "404: ${if (body.isMissing()) "Unknown" else jsonMapper().writeValueAsString(body)}",
+        cause,
+    ) {
 
     override fun statusCode(): Int = 404