release: 5.1.0

.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
 

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.0.0"
+  ".": "5.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 45
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-14d375aab89e6b212fe459805a42d6ea7d7da8eae2037ae710a187d06911be1d.yml
-openapi_spec_hash: 08b86ecbec3323717d48e4aaee48ed54
-config_hash: ce10384813f68ba3fed61c7b601b396b
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-bf858f37d7ab420841ddc6329dad8c46377308b6a5c8e935908011d0f9845e22.yml
+openapi_spec_hash: 2523952a32436e3c7fd3b55508c2e7ee
+config_hash: 53778a0b839c4f6ad34fbba051f5e8a6

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 5.1.0 (2025-04-11)
+
+Full Changelog: [v5.0.0...v5.1.0](https://github.com/Finch-API/finch-api-java/compare/v5.0.0...v5.1.0)
+
+### Features
+
+* **api:** add models for hrs benefits individuals async responses ([511b7fb](https://github.com/Finch-API/finch-api-java/commit/511b7fb4b6969bfded3c4f021753c1823b10baf1))
+* **api:** api update ([#533](https://github.com/Finch-API/finch-api-java/issues/533)) ([a7c802c](https://github.com/Finch-API/finch-api-java/commit/a7c802c84dff751a252c17ea3d4b19624792cba1))
+* **api:** benefits mutation API endpoints (create benefit, update benefit, enroll individual, unenroll individual) now properly return async response types ([#539](https://github.com/Finch-API/finch-api-java/issues/539)) ([4d1722f](https://github.com/Finch-API/finch-api-java/commit/4d1722feebfff70b762a41c6ea7c7a72299de8a8))
+* **client:** make pagination robust to missing data ([c054662](https://github.com/Finch-API/finch-api-java/commit/c054662ddf6e98fb805574d6851f8f81933bc07a))
+* **client:** support setting base URL via env var ([#535](https://github.com/Finch-API/finch-api-java/issues/535)) ([2a19f7e](https://github.com/Finch-API/finch-api-java/commit/2a19f7ec2159e69798afdb92f6f220254276a5fe))
+
+
+### Bug Fixes
+
+* **client:** bump to better jackson version ([#537](https://github.com/Finch-API/finch-api-java/issues/537)) ([4b3bc8d](https://github.com/Finch-API/finch-api-java/commit/4b3bc8d9e5a06356889f49afd96b19085c0aedfe))
+* **client:** page compilation error ([4da1190](https://github.com/Finch-API/finch-api-java/commit/4da1190d2b90298fb4d24ac48f2b9009fb39534f))
+
+
+### Chores
+
+* fix typo ([94a98e8](https://github.com/Finch-API/finch-api-java/commit/94a98e8ccff95f19fb8faf965525dd063745a3cb))
+* fix typo ([#540](https://github.com/Finch-API/finch-api-java/issues/540)) ([c56d73d](https://github.com/Finch-API/finch-api-java/commit/c56d73d2d29464841ec771edfa791fda80fb073f))
+* **internal:** expand CI branch coverage ([#536](https://github.com/Finch-API/finch-api-java/issues/536)) ([ed70465](https://github.com/Finch-API/finch-api-java/commit/ed704657d81ca00bc2e0baf40291d754b343d2aa))
+* **internal:** reduce CI branch coverage ([72adfa6](https://github.com/Finch-API/finch-api-java/commit/72adfa647da7ce56023200595f04f46379245ff8))
+
+
+### Documentation
+
+* add comments for page methods ([c054662](https://github.com/Finch-API/finch-api-java/commit/c054662ddf6e98fb805574d6851f8f81933bc07a))
+
+
+### Refactors
+
+* **client:** deduplicate page response classes ([#538](https://github.com/Finch-API/finch-api-java/issues/538)) ([c054662](https://github.com/Finch-API/finch-api-java/commit/c054662ddf6e98fb805574d6851f8f81933bc07a))
+* **client:** migrate pages to builder pattern ([#541](https://github.com/Finch-API/finch-api-java/issues/541)) ([5463e75](https://github.com/Finch-API/finch-api-java/commit/5463e75521312f9b219be62a6c7b4d090bec0754))
+
 ## 5.0.0 (2025-04-08)
 
 Full Changelog: [v4.2.0...v5.0.0](https://github.com/Finch-API/finch-api-java/compare/v4.2.0...v5.0.0)

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-java)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-java/5.0.0)
-[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/5.0.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.0.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-java)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-java/5.1.0)
+[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/5.1.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.1.0)
 
 <!-- x-release-please-end -->
 
@@ -15,7 +15,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [developer.tryfinch.com](https://developer.tryfinch.com/). Javadocs are also available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.0.0).
+The REST API documentation can be found on [developer.tryfinch.com](https://developer.tryfinch.com/). Javadocs are also available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.1.0).
 
 <!-- x-release-please-end -->
 
@@ -26,7 +26,7 @@ The REST API documentation can be found on [developer.tryfinch.com](https://deve
 ### Gradle
 
 ```kotlin
-implementation("com.tryfinch.api:finch-java:5.0.0")
+implementation("com.tryfinch.api:finch-java:5.1.0")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("com.tryfinch.api:finch-java:5.0.0")
 <dependency>
   <groupId>com.tryfinch.api</groupId>
   <artifactId>finch-java</artifactId>
-  <version>5.0.0</version>
+  <version>5.1.0</version>
 </dependency>
 ```
 
@@ -54,7 +54,7 @@ import com.tryfinch.api.models.HrisDirectoryListPage;
 import com.tryfinch.api.models.HrisDirectoryListParams;
 
 FinchClient client = FinchOkHttpClient.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` and `FINCH_WEBHOOK_SECRET` environment variables
+    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -71,7 +71,7 @@ import com.tryfinch.api.client.FinchClient;
 import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
 
 FinchClient client = FinchOkHttpClient.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` and `FINCH_WEBHOOK_SECRET` environment variables
+    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -95,19 +95,20 @@ import com.tryfinch.api.client.FinchClient;
 import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
 
 FinchClient client = FinchOkHttpClient.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` and `FINCH_WEBHOOK_SECRET` environment variables
+    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
 ```
 
 See this table for the available options:
 
-| Setter          | Environment variable   | Required | Default value |
-| --------------- | ---------------------- | -------- | ------------- |
-| `clientId`      | `FINCH_CLIENT_ID`      | false    | -             |
-| `clientSecret`  | `FINCH_CLIENT_SECRET`  | false    | -             |
-| `webhookSecret` | `FINCH_WEBHOOK_SECRET` | false    | -             |
+| Setter          | Environment variable   | Required | Default value                |
+| --------------- | ---------------------- | -------- | ---------------------------- |
+| `clientId`      | `FINCH_CLIENT_ID`      | false    | -                            |
+| `clientSecret`  | `FINCH_CLIENT_SECRET`  | false    | -                            |
+| `webhookSecret` | `FINCH_WEBHOOK_SECRET` | false    | -                            |
+| `baseUrl`       | `FINCH_BASE_URL`       | true     | `"https://api.tryfinch.com"` |
 
 > [!TIP]
 > Don't create more than one client in the same application. Each client has a connection pool and
@@ -139,7 +140,7 @@ import com.tryfinch.api.models.HrisDirectoryListParams;
 import java.util.concurrent.CompletableFuture;
 
 FinchClient client = FinchOkHttpClient.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` and `FINCH_WEBHOOK_SECRET` environment variables
+    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -157,7 +158,7 @@ import com.tryfinch.api.models.HrisDirectoryListParams;
 import java.util.concurrent.CompletableFuture;
 
 FinchClientAsync client = FinchOkHttpClientAsync.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` and `FINCH_WEBHOOK_SECRET` environment variables
+    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.tryfinch.api"
-    version = "5.0.0" // x-release-please-version
+    version = "5.1.0" // x-release-please-version
 }
 
 subprojects {

finch-java-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt

@@ -29,14 +29,10 @@ class FinchOkHttpClient 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
@@ -190,7 +186,7 @@ class FinchOkHttpClient private constructor() {
                 clientOptions
                     .httpClient(
                         OkHttpClient.builder()
-                            .baseUrl(baseUrl)
+                            .baseUrl(clientOptions.baseUrl())
                             .timeout(timeout)
                             .proxy(proxy)
                             .build()

finch-java-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt

@@ -29,14 +29,10 @@ class FinchOkHttpClientAsync 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
@@ -190,7 +186,7 @@ class FinchOkHttpClientAsync private constructor() {
                 clientOptions
                     .httpClient(
                         OkHttpClient.builder()
-                            .baseUrl(baseUrl)
+                            .baseUrl(clientOptions.baseUrl())
                             .timeout(timeout)
                             .proxy(proxy)
                             .build()

finch-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")
 

finch-java-core/src/main/kotlin/com/tryfinch/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,

finch-java-core/src/main/kotlin/com/tryfinch/api/core/ClientOptions.kt

@@ -222,7 +222,10 @@ private constructor(
 
         fun removeAllQueryParams(keys: Set<String>) = apply { queryParams.removeAll(keys) }
 
+        fun baseUrl(): String = baseUrl
+
         fun fromEnv() = apply {
+            System.getenv("FINCH_BASE_URL")?.let { baseUrl(it) }
             System.getenv("FINCH_CLIENT_ID")?.let { clientId(it) }
             System.getenv("FINCH_CLIENT_SECRET")?.let { clientSecret(it) }
             System.getenv("FINCH_WEBHOOK_SECRET")?.let { webhookSecret(it) }