orbcorp · stainless-app · Apr 10, 2025 · Apr 9, 2025 · Apr 9, 2025 · Apr 9, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,8 +12,6 @@ jobs:
   lint:
     name: lint
     runs-on: ubuntu-latest
-
-
     steps:
       - uses: actions/checkout@v4
 
@@ -34,7 +32,6 @@ jobs:
   test:
     name: test
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v4
 

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.55.0"
+  ".": "0.56.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.56.0 (2025-04-09)
+
+Full Changelog: [v0.55.0...v0.56.0](https://github.com/orbcorp/orb-java/compare/v0.55.0...v0.56.0)
+
+### Features
+
+* **client:** make pagination robust to missing data ([bf8c89e](https://github.com/orbcorp/orb-java/commit/bf8c89e3e5148a99afd9b9e5f211dd3002c2d88e))
+* **client:** support setting base URL via env var ([#397](https://github.com/orbcorp/orb-java/issues/397)) ([4ac10b3](https://github.com/orbcorp/orb-java/commit/4ac10b3cf164a76c7da1e0c5fc12aeec0338d0d3))
+
+
+### Bug Fixes
+
+* **client:** bump to better jackson version ([#400](https://github.com/orbcorp/orb-java/issues/400)) ([b9c0a00](https://github.com/orbcorp/orb-java/commit/b9c0a00b0181bfbaf7a9a2f670b98000dfa4b996))
+
+
+### Chores
+
+* **internal:** expand CI branch coverage ([#399](https://github.com/orbcorp/orb-java/issues/399)) ([17d8399](https://github.com/orbcorp/orb-java/commit/17d8399351f5affa7a89fbc79df9e88c732c1330))
+* **internal:** reduce CI branch coverage ([06a8495](https://github.com/orbcorp/orb-java/commit/06a84957b55d697cbb0bd3a8c6f9a4a02f95d90c))
+
+
+### Documentation
+
+* add comments for page methods ([bf8c89e](https://github.com/orbcorp/orb-java/commit/bf8c89e3e5148a99afd9b9e5f211dd3002c2d88e))
+
+
+### Refactors
+
+* **client:** deduplicate page response classes ([#401](https://github.com/orbcorp/orb-java/issues/401)) ([bf8c89e](https://github.com/orbcorp/orb-java/commit/bf8c89e3e5148a99afd9b9e5f211dd3002c2d88e))
+* **client:** migrate pages to builder pattern ([#402](https://github.com/orbcorp/orb-java/issues/402)) ([bbcd954](https://github.com/orbcorp/orb-java/commit/bbcd9545d5fad36f5b241ecc5515b44454533265))
+
 ## 0.55.0 (2025-04-08)
 
 Full Changelog: [v0.54.0...v0.55.0](https://github.com/orbcorp/orb-java/compare/v0.54.0...v0.55.0)

diff --git a/README.md b/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/0.55.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/0.56.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:0.55.0")
+implementation("com.withorb.api:orb-java:0.56.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("com.withorb.api:orb-java:0.55.0")
 <dependency>
   <groupId>com.withorb.api</groupId>
   <artifactId>orb-java</artifactId>
-  <version>0.55.0</version>
+  <version>0.56.0</version>
 </dependency>
 ```
 
@@ -46,7 +46,7 @@ import com.withorb.api.client.okhttp.OrbOkHttpClient;
 import com.withorb.api.models.Customer;
 import com.withorb.api.models.CustomerCreateParams;
 
-// Configures using the `ORB_API_KEY` and `ORB_WEBHOOK_SECRET` environment variables
+// Configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
 OrbClient client = OrbOkHttpClient.fromEnv();
 
 CustomerCreateParams params = CustomerCreateParams.builder()
@@ -64,7 +64,7 @@ Configure the client using environment variables:
 import com.withorb.api.client.OrbClient;
 import com.withorb.api.client.okhttp.OrbOkHttpClient;
 
-// Configures using the `ORB_API_KEY` and `ORB_WEBHOOK_SECRET` environment variables
+// Configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
 OrbClient client = OrbOkHttpClient.fromEnv();
 ```
 
@@ -86,18 +86,19 @@ import com.withorb.api.client.OrbClient;
 import com.withorb.api.client.okhttp.OrbOkHttpClient;
 
 OrbClient client = OrbOkHttpClient.builder()
-    // Configures using the `ORB_API_KEY` and `ORB_WEBHOOK_SECRET` environment variables
+    // Configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
     .fromEnv()
     .apiKey("My API Key")
     .build();
 ```
 
 See this table for the available options:
 
-| Setter          | Environment variable | Required | Default value |
-| --------------- | -------------------- | -------- | ------------- |
-| `apiKey`        | `ORB_API_KEY`        | true     | -             |
-| `webhookSecret` | `ORB_WEBHOOK_SECRET` | false    | -             |
+| Setter          | Environment variable | Required | Default value                  |
+| --------------- | -------------------- | -------- | ------------------------------ |
+| `apiKey`        | `ORB_API_KEY`        | true     | -                              |
+| `webhookSecret` | `ORB_WEBHOOK_SECRET` | false    | -                              |
+| `baseUrl`       | `ORB_BASE_URL`       | true     | `"https://api.withorb.com/v1"` |
 
 > [!TIP]
 > Don't create more than one client in the same application. Each client has a connection pool and
@@ -128,7 +129,7 @@ import com.withorb.api.models.Customer;
 import com.withorb.api.models.CustomerCreateParams;
 import java.util.concurrent.CompletableFuture;
 
-// Configures using the `ORB_API_KEY` and `ORB_WEBHOOK_SECRET` environment variables
+// Configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
 OrbClient client = OrbOkHttpClient.fromEnv();
 
 CustomerCreateParams params = CustomerCreateParams.builder()
@@ -147,7 +148,7 @@ import com.withorb.api.models.Customer;
 import com.withorb.api.models.CustomerCreateParams;
 import java.util.concurrent.CompletableFuture;
 
-// Configures using the `ORB_API_KEY` and `ORB_WEBHOOK_SECRET` environment variables
+// Configures using the `ORB_API_KEY`, `ORB_WEBHOOK_SECRET` and `ORB_BASE_URL` environment variables
 OrbClientAsync client = OrbOkHttpClientAsync.fromEnv();
 
 CustomerCreateParams params = CustomerCreateParams.builder()

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,4 +1,4 @@
 allprojects {
     group = "com.withorb.api"
-    version = "0.55.0" // x-release-please-version
+    version = "0.56.0" // x-release-please-version
 }
diff --git a/orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClient.kt b/orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClient.kt
@@ -29,14 +29,10 @@ class OrbOkHttpClient private constructor() {
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
-        private var baseUrl: String = ClientOptions.PRODUCTION_URL
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
-        fun baseUrl(baseUrl: String) = apply {
-            clientOptions.baseUrl(baseUrl)
-            this.baseUrl = baseUrl
-        }
+        fun baseUrl(baseUrl: String) = apply { clientOptions.baseUrl(baseUrl) }
 
         /**
          * Whether to throw an exception if any of the Jackson versions detected at runtime are
@@ -177,7 +173,7 @@ class OrbOkHttpClient private constructor() {
                 clientOptions
                     .httpClient(
                         OkHttpClient.builder()
-                            .baseUrl(baseUrl)
+                            .baseUrl(clientOptions.baseUrl())
                             .timeout(timeout)
                             .proxy(proxy)
                             .build()

diff --git a/orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClientAsync.kt b/orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClientAsync.kt
@@ -29,14 +29,10 @@ class OrbOkHttpClientAsync private constructor() {
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
-        private var baseUrl: String = ClientOptions.PRODUCTION_URL
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
-        fun baseUrl(baseUrl: String) = apply {
-            clientOptions.baseUrl(baseUrl)
-            this.baseUrl = baseUrl
-        }
+        fun baseUrl(baseUrl: String) = apply { clientOptions.baseUrl(baseUrl) }
 
         /**
          * Whether to throw an exception if any of the Jackson versions detected at runtime are
@@ -177,7 +173,7 @@ class OrbOkHttpClientAsync private constructor() {
                 clientOptions
                     .httpClient(
                         OkHttpClient.builder()
-                            .baseUrl(baseUrl)
+                            .baseUrl(clientOptions.baseUrl())
                             .timeout(timeout)
                             .proxy(proxy)
                             .build()

diff --git a/orb-java-core/build.gradle.kts b/orb-java-core/build.gradle.kts
@@ -17,14 +17,14 @@ configurations.all {
 }
 
 dependencies {
-    api("com.fasterxml.jackson.core:jackson-core:2.18.1")
-    api("com.fasterxml.jackson.core:jackson-databind:2.18.1")
+    api("com.fasterxml.jackson.core:jackson-core:2.18.2")
+    api("com.fasterxml.jackson.core:jackson-databind:2.18.2")
     api("com.google.errorprone:error_prone_annotations:2.33.0")
 
-    implementation("com.fasterxml.jackson.core:jackson-annotations:2.18.1")
-    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.1")
-    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.1")
-    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.1")
+    implementation("com.fasterxml.jackson.core:jackson-annotations:2.18.2")
+    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2")
+    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.2")
+    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.2")
     implementation("org.apache.httpcomponents.core5:httpcore5:5.2.4")
     implementation("org.apache.httpcomponents.client5:httpclient5:5.3.1")
 

diff --git a/orb-java-core/src/main/kotlin/com/withorb/api/core/Check.kt b/orb-java-core/src/main/kotlin/com/withorb/api/core/Check.kt
@@ -47,6 +47,7 @@ internal fun checkMaxLength(name: String, value: String, maxLength: Int): String
 internal fun checkJacksonVersionCompatibility() {
     val incompatibleJacksonVersions =
         RUNTIME_JACKSON_VERSIONS.mapNotNull {
+            val badVersionReason = BAD_JACKSON_VERSIONS[it.toString()]
             when {
                 it.majorVersion != MINIMUM_JACKSON_VERSION.majorVersion ->
                     it to "incompatible major version"
@@ -55,6 +56,7 @@ internal fun checkJacksonVersionCompatibility() {
                 it.minorVersion == MINIMUM_JACKSON_VERSION.minorVersion &&
                     it.patchLevel < MINIMUM_JACKSON_VERSION.patchLevel ->
                     it to "patch version too low"
+                badVersionReason != null -> it to badVersionReason
                 else -> null
             }
         }
@@ -77,6 +79,8 @@ Double-check that you are depending on compatible Jackson versions.
 }
 
 private val MINIMUM_JACKSON_VERSION: Version = VersionUtil.parseVersion("2.13.4", null, null)
+private val BAD_JACKSON_VERSIONS: Map<String, String> =
+    mapOf("2.18.1" to "due to https://github.com/FasterXML/jackson-databind/issues/4639")
 private val RUNTIME_JACKSON_VERSIONS: List<Version> =
     listOf(
         com.fasterxml.jackson.core.json.PackageVersion.VERSION,

diff --git a/orb-java-core/src/main/kotlin/com/withorb/api/core/ClientOptions.kt b/orb-java-core/src/main/kotlin/com/withorb/api/core/ClientOptions.kt
@@ -197,7 +197,10 @@ private constructor(
 
         fun removeAllQueryParams(keys: Set<String>) = apply { queryParams.removeAll(keys) }
 
+        fun baseUrl(): String = baseUrl
+
         fun fromEnv() = apply {
+            System.getenv("ORB_BASE_URL")?.let { baseUrl(it) }
             System.getenv("ORB_API_KEY")?.let { apiKey(it) }
             System.getenv("ORB_WEBHOOK_SECRET")?.let { webhookSecret(it) }
         }