release: 1.8.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.7.0"
+  ".": "1.8.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 116
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-a44cccd16bb58080f7cc0669999403f6ed3f77287fad901caa6fd2523f2fbafd.yml
-openapi_spec_hash: af6444648d0b2a70b7f7ad234bd37541
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-1aabbd8715a871e993abf67f0bf9c1d6793b4f197c4b2f11fc7a76453590cd6c.yml
+openapi_spec_hash: 3e5878f87e74881d882a69e1ccdc25a3
 config_hash: 1f535c1fa222aacf28b636eed21bec72

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.8.0 (2025-07-24)
+
+Full Changelog: [v1.7.0...v1.8.0](https://github.com/orbcorp/orb-java/compare/v1.7.0...v1.8.0)
+
+### Features
+
+* **api:** api update ([d9b5f74](https://github.com/orbcorp/orb-java/commit/d9b5f744ddeb6fd8e74ad62bc7e36cf187d3078d))
+* **client:** add `{QueryParams,Headers}#put(String, JsonValue)` methods ([1985d12](https://github.com/orbcorp/orb-java/commit/1985d1259d8f0737819b815e198ee4b3455499ce))
+
+
+### Chores
+
+* **internal:** remove unnecessary `[...]` in `[@see](https://github.com/see)` ([cc42cf6](https://github.com/orbcorp/orb-java/commit/cc42cf60494abf45d48cf3043735349e04787805))
+
+
+### Documentation
+
+* fix missing readme comment ([3c649f1](https://github.com/orbcorp/orb-java/commit/3c649f13490f3f6a9c2ac40f0b13c92671314af3))
+* more code comments ([0fac99b](https://github.com/orbcorp/orb-java/commit/0fac99b1da5ef2ddc8b7a73c3d5aa2601d9a8958))
+
 ## 1.7.0 (2025-07-21)
 
 Full Changelog: [v1.6.0...v1.7.0](https://github.com/orbcorp/orb-java/compare/v1.6.0...v1.7.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.withorb.api/orb-java)](https://central.sonatype.com/artifact/com.withorb.api/orb-java/1.7.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.withorb.api/orb-java)](https://central.sonatype.com/artifact/com.withorb.api/orb-java/1.8.0)
 
 <!-- x-release-please-end -->
 
@@ -19,7 +19,7 @@ The REST API documentation can be found on [docs.withorb.com](https://docs.witho
 ### Gradle
 
 ```kotlin
-implementation("com.withorb.api:orb-java:1.7.0")
+implementation("com.withorb.api:orb-java:1.8.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("com.withorb.api:orb-java:1.7.0")
 <dependency>
   <groupId>com.withorb.api</groupId>
   <artifactId>orb-java</artifactId>
-  <version>1.7.0</version>
+  <version>1.8.0</version>
 </dependency>
 ```
 
@@ -89,7 +89,7 @@ import com.withorb.api.client.okhttp.OrbOkHttpClient;
 
 OrbClient client = OrbOkHttpClient.builder()
     // Configures using the `orb.apiKey`, `orb.webhookSecret` and `orb.baseUrl` system properties
-    Or configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
+    // Or configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
     .fromEnv()
     .apiKey("My API Key")
     .build();
@@ -376,7 +376,7 @@ If the SDK threw an exception, but you're _certain_ the version is compatible, t
 
 ### Retries
 
-The SDK automatically retries 2 times by default, with a short exponential backoff.
+The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
 
 Only the following error types are retried:
 
@@ -386,7 +386,7 @@ Only the following error types are retried:
 - 429 Rate Limit
 - 5xx Internal
 
-The API may also explicitly instruct the SDK to retry or not retry a response.
+The API may also explicitly instruct the SDK to retry or not retry a request.
 
 To set a custom number of retries, configure the client using the `maxRetries` method:
 

build.gradle.kts

@@ -1,4 +1,4 @@
 allprojects {
     group = "com.withorb.api"
-    version = "1.7.0" // x-release-please-version
+    version = "1.8.0" // x-release-please-version
 }

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClient.kt

@@ -7,7 +7,9 @@ import com.withorb.api.client.OrbClient
 import com.withorb.api.client.OrbClientImpl
 import com.withorb.api.core.ClientOptions
 import com.withorb.api.core.Timeout
+import com.withorb.api.core.http.AsyncStreamResponse
 import com.withorb.api.core.http.Headers
+import com.withorb.api.core.http.HttpClient
 import com.withorb.api.core.http.QueryParams
 import com.withorb.api.core.jsonMapper
 import java.net.Proxy
@@ -20,13 +22,22 @@ import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * A class that allows building an instance of [OrbClient] with [OkHttpClient] as the underlying
+ * [HttpClient].
+ */
 class OrbOkHttpClient private constructor() {
 
     companion object {
 
-        /** Returns a mutable builder for constructing an instance of [OrbOkHttpClient]. */
+        /** Returns a mutable builder for constructing an instance of [OrbClient]. */
         @JvmStatic fun builder() = Builder()
 
+        /**
+         * Returns a client configured using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         @JvmStatic fun fromEnv(): OrbClient = builder().fromEnv().build()
     }
 
@@ -103,23 +114,58 @@ class OrbOkHttpClient private constructor() {
             clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
         }
 
+        /**
+         * The Jackson JSON mapper to use for serializing and deserializing JSON.
+         *
+         * Defaults to [com.withorb.api.core.jsonMapper]. The default is usually sufficient and
+         * rarely needs to be overridden.
+         */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The executor to use for running [AsyncStreamResponse.Handler] callbacks.
+         *
+         * Defaults to a dedicated cached thread pool.
+         */
         fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {
             clientOptions.streamHandlerExecutor(streamHandlerExecutor)
         }
 
+        /**
+         * The clock to use for operations that require timing, like retries.
+         *
+         * This is primarily useful for using a fake clock in tests.
+         *
+         * Defaults to [Clock.systemUTC].
+         */
         fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
 
+        /**
+         * The base URL to use for every request.
+         *
+         * Defaults to the production environment: `https://api.withorb.com/v1`.
+         */
         fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
 
         /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
         fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
 
+        /**
+         * Whether to call `validate` on every response before returning it.
+         *
+         * 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 {
             clientOptions.responseValidation(responseValidation)
         }
 
+        /**
+         * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+         * retries.
+         *
+         * Defaults to [Timeout.default].
+         */
         fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
 
         /**
@@ -131,6 +177,21 @@ class OrbOkHttpClient private constructor() {
          */
         fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
 
+        /**
+         * The maximum number of times to retry failed requests, with a short exponential backoff
+         * between requests.
+         *
+         * Only the following error types are retried:
+         * - Connection errors (for example, due to a network connectivity problem)
+         * - 408 Request Timeout
+         * - 409 Conflict
+         * - 429 Rate Limit
+         * - 5xx Internal
+         *
+         * The API may also explicitly instruct the SDK to retry or not retry a request.
+         *
+         * Defaults to 2.
+         */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -223,6 +284,11 @@ class OrbOkHttpClient private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
+        /**
+         * Updates configuration using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         /**

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClientAsync.kt

@@ -7,7 +7,9 @@ import com.withorb.api.client.OrbClientAsync
 import com.withorb.api.client.OrbClientAsyncImpl
 import com.withorb.api.core.ClientOptions
 import com.withorb.api.core.Timeout
+import com.withorb.api.core.http.AsyncStreamResponse
 import com.withorb.api.core.http.Headers
+import com.withorb.api.core.http.HttpClient
 import com.withorb.api.core.http.QueryParams
 import com.withorb.api.core.jsonMapper
 import java.net.Proxy
@@ -20,13 +22,22 @@ import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * A class that allows building an instance of [OrbClientAsync] with [OkHttpClient] as the
+ * underlying [HttpClient].
+ */
 class OrbOkHttpClientAsync private constructor() {
 
     companion object {
 
-        /** Returns a mutable builder for constructing an instance of [OrbOkHttpClientAsync]. */
+        /** Returns a mutable builder for constructing an instance of [OrbClientAsync]. */
         @JvmStatic fun builder() = Builder()
 
+        /**
+         * Returns a client configured using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         @JvmStatic fun fromEnv(): OrbClientAsync = builder().fromEnv().build()
     }
 
@@ -103,23 +114,58 @@ class OrbOkHttpClientAsync private constructor() {
             clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
         }
 
+        /**
+         * The Jackson JSON mapper to use for serializing and deserializing JSON.
+         *
+         * Defaults to [com.withorb.api.core.jsonMapper]. The default is usually sufficient and
+         * rarely needs to be overridden.
+         */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The executor to use for running [AsyncStreamResponse.Handler] callbacks.
+         *
+         * Defaults to a dedicated cached thread pool.
+         */
         fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {
             clientOptions.streamHandlerExecutor(streamHandlerExecutor)
         }
 
+        /**
+         * The clock to use for operations that require timing, like retries.
+         *
+         * This is primarily useful for using a fake clock in tests.
+         *
+         * Defaults to [Clock.systemUTC].
+         */
         fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
 
+        /**
+         * The base URL to use for every request.
+         *
+         * Defaults to the production environment: `https://api.withorb.com/v1`.
+         */
         fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
 
         /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
         fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
 
+        /**
+         * Whether to call `validate` on every response before returning it.
+         *
+         * 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 {
             clientOptions.responseValidation(responseValidation)
         }
 
+        /**
+         * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+         * retries.
+         *
+         * Defaults to [Timeout.default].
+         */
         fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
 
         /**
@@ -131,6 +177,21 @@ class OrbOkHttpClientAsync private constructor() {
          */
         fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
 
+        /**
+         * The maximum number of times to retry failed requests, with a short exponential backoff
+         * between requests.
+         *
+         * Only the following error types are retried:
+         * - Connection errors (for example, due to a network connectivity problem)
+         * - 408 Request Timeout
+         * - 409 Conflict
+         * - 429 Rate Limit
+         * - 5xx Internal
+         *
+         * The API may also explicitly instruct the SDK to retry or not retry a request.
+         *
+         * Defaults to 2.
+         */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -223,6 +284,11 @@ class OrbOkHttpClientAsync private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
+        /**
+         * Updates configuration using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         /**