Finch-API · stainless-app · Feb 8, 2025 · Jan 14, 2025 · Jan 14, 2025 · Jan 14, 2025
@@ -1,3 +1,3 @@
 {
-  ".": "3.3.0"
+  ".": "4.0.0"
 }
@@ -1,2 +1,2 @@
 configured_endpoints: 40
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-77520f5037161db86208e3a9d3f36f39e971a8ee10b1d9972a22c084fcf21845.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-97bf4795deec23d1bfd3b0b5fd77c2a93c87f10e5fa3375ab30f4a877be97f53.yml
@@ -1,5 +1,72 @@
 # Changelog
 
+## 4.0.0 (2025-02-05)
+
+Full Changelog: [v3.3.0...v4.0.0](https://github.com/Finch-API/finch-api-java/compare/v3.3.0...v4.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **client:** better union variant method and variable names ([#410](https://github.com/Finch-API/finch-api-java/issues/410))
+
+### Features
+
+* **api:** api update ([#418](https://github.com/Finch-API/finch-api-java/issues/418)) ([1e88c1b](https://github.com/Finch-API/finch-api-java/commit/1e88c1b166a5a153372ee6bc5a6e1693822cc9fa))
+* **api:** api update ([#426](https://github.com/Finch-API/finch-api-java/issues/426)) ([77e6a73](https://github.com/Finch-API/finch-api-java/commit/77e6a7383806b0615a3bca5e25094b54cf427420))
+* **api:** api update ([#427](https://github.com/Finch-API/finch-api-java/issues/427)) ([daf9de7](https://github.com/Finch-API/finch-api-java/commit/daf9de711530f47caf431d316f682c82139cd26a))
+* **client:** add `_queryParams` and `_headers` methods ([#419](https://github.com/Finch-API/finch-api-java/issues/419)) ([2a3c658](https://github.com/Finch-API/finch-api-java/commit/2a3c6582c5179b922d9729535c47e9383efcb620))
+* **client:** add `close` method ([#412](https://github.com/Finch-API/finch-api-java/issues/412)) ([d9b722b](https://github.com/Finch-API/finch-api-java/commit/d9b722b1d27703dd7bb5a26b962ab7df102a030b))
+* **client:** better union variant method and variable names ([#410](https://github.com/Finch-API/finch-api-java/issues/410)) ([d0db606](https://github.com/Finch-API/finch-api-java/commit/d0db606cfd7914c13915861498bd32340ff9f9f3))
+* **client:** send client-side timeout headers ([#428](https://github.com/Finch-API/finch-api-java/issues/428)) ([d17227d](https://github.com/Finch-API/finch-api-java/commit/d17227dcce3a87afae057009635f749908e6397f))
+
+
+### Bug Fixes
+
+* **api:** add missing `@MustBeClosed` annotations ([#429](https://github.com/Finch-API/finch-api-java/issues/429)) ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **api:** switch `CompletableFuture&lt;Void&gt;` to `CompletableFuture<Void?>` ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **client:** add missing validation calls on response ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **client:** always provide a body for `PATCH` methods ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **client:** compiler errors ([#422](https://github.com/Finch-API/finch-api-java/issues/422)) ([2694656](https://github.com/Finch-API/finch-api-java/commit/2694656b93676e6758c71fc55beccf74fe495e00))
+* **client:** don't leak responses when retrying ([#423](https://github.com/Finch-API/finch-api-java/issues/423)) ([1c877e6](https://github.com/Finch-API/finch-api-java/commit/1c877e649c7907d3140dbd1e5d437b45db01672f))
+* **client:** make service impl constructors internal ([#405](https://github.com/Finch-API/finch-api-java/issues/405)) ([38d434d](https://github.com/Finch-API/finch-api-java/commit/38d434d35ed917af6b4e699db6a7928e15f898a3))
+* **client:** make some classes and constructors non-public ([#416](https://github.com/Finch-API/finch-api-java/issues/416)) ([0a1b627](https://github.com/Finch-API/finch-api-java/commit/0a1b627cb52cf11b76f497ad379e98e30e1a9559))
+
+
+### Chores
+
+* add max retries to test ([#411](https://github.com/Finch-API/finch-api-java/issues/411)) ([e3831a7](https://github.com/Finch-API/finch-api-java/commit/e3831a7eec0fda1e05cc29ce5fbd77a23b05f308))
+* **internal:** add and tweak check functions ([#401](https://github.com/Finch-API/finch-api-java/issues/401)) ([a08f4ba](https://github.com/Finch-API/finch-api-java/commit/a08f4ba13b492b408550783c8306668039963250))
+* **internal:** codegen related update ([#394](https://github.com/Finch-API/finch-api-java/issues/394)) ([94b4589](https://github.com/Finch-API/finch-api-java/commit/94b45894c92283b2f24a8c0c9938dc456203e7e9))
+* **internal:** codegen related update ([#425](https://github.com/Finch-API/finch-api-java/issues/425)) ([84cd37e](https://github.com/Finch-API/finch-api-java/commit/84cd37eb0660362f57d92404e4ca17ad4c8340fa))
+* **internal:** extract a `checkRequired` function ([#400](https://github.com/Finch-API/finch-api-java/issues/400)) ([f0fec86](https://github.com/Finch-API/finch-api-java/commit/f0fec86853463134ddda5385e801c568de18487c))
+* **internal:** fix up root `build.gradle.kts` formatting ([#396](https://github.com/Finch-API/finch-api-java/issues/396)) ([595151c](https://github.com/Finch-API/finch-api-java/commit/595151c73573c47ce6d789431c35f3ad1665eac6))
+* **internal:** improve `RetryingHttpClientTest` ([#421](https://github.com/Finch-API/finch-api-java/issues/421)) ([6f997fe](https://github.com/Finch-API/finch-api-java/commit/6f997fed271b1d2ffab8c54c365d32993ea4b0b1))
+* **internal:** minor formatting/style changes ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **internal:** remove some unnecessary `constructor` keywords ([0a1b627](https://github.com/Finch-API/finch-api-java/commit/0a1b627cb52cf11b76f497ad379e98e30e1a9559))
+* **internal:** remove unused Gradle imports ([#397](https://github.com/Finch-API/finch-api-java/issues/397)) ([c5f656d](https://github.com/Finch-API/finch-api-java/commit/c5f656d35f9642c946d18330bec0a453b522f234))
+* **internal:** remove unused or unnecessary Gradle imports ([#398](https://github.com/Finch-API/finch-api-java/issues/398)) ([5d706bc](https://github.com/Finch-API/finch-api-java/commit/5d706bc05046466b2b7a3ee43ec85c21943cb731))
+* **internal:** rename some tests ([abe41ab](https://github.com/Finch-API/finch-api-java/commit/abe41abe42c306d6c19df15151dcea02908a4e98))
+* **internal:** swap `checkNotNull` to `checkRequired` ([#409](https://github.com/Finch-API/finch-api-java/issues/409)) ([4018e4c](https://github.com/Finch-API/finch-api-java/commit/4018e4c4154bba72bb09a8421c1c75128da64c9c))
+* **internal:** tweak client options nullability handling ([a08f4ba](https://github.com/Finch-API/finch-api-java/commit/a08f4ba13b492b408550783c8306668039963250))
+* **internal:** update some gradle formatting ([#399](https://github.com/Finch-API/finch-api-java/issues/399)) ([623b174](https://github.com/Finch-API/finch-api-java/commit/623b1747a63e47b165e18cf5428faa9c9baa8d98))
+* **internal:** upgrade kotlin compiler and gradle ([#403](https://github.com/Finch-API/finch-api-java/issues/403)) ([0d0766b](https://github.com/Finch-API/finch-api-java/commit/0d0766b6c48e7efd60dbb7f3e2306771d307526c))
+* simplify examples involving lists ([#402](https://github.com/Finch-API/finch-api-java/issues/402)) ([4520086](https://github.com/Finch-API/finch-api-java/commit/4520086fb9d7c43ffec2386fa585e3a56107f7ec))
+
+
+### Documentation
+
+* `async` and `sync` method comments ([#415](https://github.com/Finch-API/finch-api-java/issues/415)) ([ab65f2f](https://github.com/Finch-API/finch-api-java/commit/ab65f2fe56ddd3199441d48921ef60f94eda85bb))
+* add client documentation ([#414](https://github.com/Finch-API/finch-api-java/issues/414)) ([d4b8051](https://github.com/Finch-API/finch-api-java/commit/d4b805129069eaa3d584abc78274f8b017dce885))
+* add more documentation ([#404](https://github.com/Finch-API/finch-api-java/issues/404)) ([1cef90d](https://github.com/Finch-API/finch-api-java/commit/1cef90d50b2920f67b9455c0b1a1cdad5d86a0d0))
+* builder, enum, and union comments ([#417](https://github.com/Finch-API/finch-api-java/issues/417)) ([1e1e28e](https://github.com/Finch-API/finch-api-java/commit/1e1e28e262030d8a05af6a9c3736f91650bede4f))
+* fix incorrect additional properties info ([#424](https://github.com/Finch-API/finch-api-java/issues/424)) ([856e1c9](https://github.com/Finch-API/finch-api-java/commit/856e1c9f646fb80df8f6751634d6f39ccdf633b7))
+* move up requirements section ([#408](https://github.com/Finch-API/finch-api-java/issues/408)) ([a595f32](https://github.com/Finch-API/finch-api-java/commit/a595f323b1bc0d26ef4ffda2b16f747c7d062660))
+* update readme ([#406](https://github.com/Finch-API/finch-api-java/issues/406)) ([31e854c](https://github.com/Finch-API/finch-api-java/commit/31e854c04ea5f0e9271d40b96e3fb313155de390))
+
+
+### Refactors
+
+* **internal:** extract request preparation logic ([2a3c658](https://github.com/Finch-API/finch-api-java/commit/2a3c6582c5179b922d9729535c47e9383efcb620))
+
 ## 3.3.0 (2025-01-09)
 
 Full Changelog: [v3.2.0...v3.3.0](https://github.com/Finch-API/finch-api-java/compare/v3.2.0...v3.3.0)

@@ -2,46 +2,48 @@
 
 <!-- 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/3.3.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/4.0.0)
 
 <!-- x-release-please-end -->
 
-The Finch Java SDK provides convenient access to the Finch REST API from applications written in Java. It includes helper classes with helpful types and documentation for every request and response property.
+The Finch Java SDK provides convenient access to the Finch REST API from applications written in Java.
 
 The Finch Java SDK is similar to the Finch Kotlin SDK but with minor differences that make it more ergonomic for use in Java, such as `Optional` instead of nullable values, `Stream` instead of `Sequence`, and `CompletableFuture` instead of suspend functions.
 
 It is generated with [Stainless](https://www.stainlessapi.com/).
 
-## Documentation
-
 The REST API documentation can be found [in the Finch Documentation Center](https://developer.tryfinch.com/).
 
 ---
 
-## Getting started
-
-### Install dependencies
-
-#### Gradle
+## Installation
 
 <!-- x-release-please-start-version -->
 
+### Gradle
+
 ```kotlin
-implementation("com.tryfinch.api:finch-java:3.3.0")
+implementation("com.tryfinch.api:finch-java:4.0.0")
 ```
 
-#### Maven
+### Maven
 
 ```xml
 <dependency>
     <groupId>com.tryfinch.api</groupId>
     <artifactId>finch-java</artifactId>
-    <version>3.3.0</version>
+    <version>4.0.0</version>
 </dependency>
 ```
 
 <!-- x-release-please-end -->
 
+## Requirements
+
+This library requires Java 8 or later.
+
+## Usage
+
 ### Configure the client
 
 Use `FinchOkHttpClient.builder()` to configure the client.
@@ -130,19 +132,7 @@ See [Pagination](#pagination) below for more information on transparently workin
 
 To make a request to the Finch API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `HrisDirectoryListParams.builder()` to pass to the `list` method of the `directory` service.
-
-Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using the `putAdditionalProperty` method.
-
-```java
-import com.tryfinch.api.core.JsonValue;
-import com.tryfinch.api.models.HrisDirectoryListParams;
-
-HrisDirectoryListParams params = HrisDirectoryListParams.builder()
-    // ... normal properties
-    .putAdditionalProperty("secret_param", JsonValue.from("4242"))
-    .build();
-```
+See [Undocumented request params](#undocumented-request-params) for how to send arbitrary parameters.
 
 ## Responses
 
@@ -336,18 +326,26 @@ This library is typed for convenient access to the documented API. If you need t
 
 ### Undocumented request params
 
-To make requests using undocumented parameters, you can provide or override parameters on the params object while building it.
+In [Example: creating a resource](#example-creating-a-resource) above, we used the `HrisDirectoryListParams.builder()` to pass to the `list` method of the `directory` service.
+
+Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using raw setters:
 
 ```java
-FooCreateParams address = FooCreateParams.builder()
-    .id("my_id")
-    .putAdditionalProperty("secret_prop", JsonValue.from("hello"))
+import com.tryfinch.api.core.JsonValue;
+import com.tryfinch.api.models.HrisDirectoryListParams;
+
+HrisDirectoryListParams params = HrisDirectoryListParams.builder()
+    .putAdditionalHeader("Secret-Header", "42")
+    .putAdditionalQueryParam("secret_query_param", "42")
+    .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
     .build();
 ```
 
+You can also use the `putAdditionalProperty` method on nested headers, query params, or body objects.
+
 ### Undocumented response properties
 
-To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like `._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type.
+To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like `res._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type.
 
 ## Logging
 
@@ -375,7 +373,3 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
 We are keen for your feedback; please open an [issue](https://www.github.com/Finch-API/finch-api-java/issues) with questions, bugs, or suggestions.
-
-## Requirements
-
-This library requires Java 8 or later.
@@ -1,10 +1,4 @@
-plugins {
-
-}
-
 allprojects {
     group = "com.tryfinch.api"
-    version = "3.3.0" // x-release-please-version
+    version = "4.0.0" // x-release-please-version
 }
-
-
@@ -1,6 +1,6 @@
 plugins {
     `kotlin-dsl`
-    kotlin("jvm") version "1.9.22"
+    kotlin("jvm") version "2.1.0"
     id("com.vanniktech.maven.publish") version "0.28.0"
 }
 

@@ -1,9 +1,5 @@
 import com.diffplug.gradle.spotless.SpotlessExtension
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-import com.vanniktech.maven.publish.JavaLibrary
-import com.vanniktech.maven.publish.JavadocJar
-import com.vanniktech.maven.publish.MavenPublishBaseExtension
-import com.vanniktech.maven.publish.SonatypeHost
 
 plugins {
     `java-library`

@@ -1,6 +1,5 @@
 import com.diffplug.gradle.spotless.SpotlessExtension
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
-import com.vanniktech.maven.publish.*
 
 plugins {
     id("finch.java")
@@ -22,8 +21,12 @@ configure<SpotlessExtension> {
 
 tasks.withType<KotlinCompile>().configureEach {
     kotlinOptions {
-        allWarningsAsErrors = true
-        freeCompilerArgs = listOf("-Xjvm-default=all", "-Xjdk-release=1.8")
+        freeCompilerArgs = listOf(
+          "-Xjvm-default=all",
+          "-Xjdk-release=1.8",
+          // Suppress deprecation warnings because we may still reference and test deprecated members.
+          "-Xsuppress-warning=DEPRECATION"
+        )
         jvmTarget = "1.8"
     }
 }
@@ -1,10 +1,3 @@
-import org.gradle.api.publish.PublishingExtension
-import org.gradle.api.publish.maven.MavenPublication
-import org.gradle.kotlin.dsl.configure
-import org.gradle.kotlin.dsl.register
-import org.gradle.kotlin.dsl.get
-import com.vanniktech.maven.publish.JavaLibrary
-import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.MavenPublishBaseExtension
 import com.vanniktech.maven.publish.SonatypeHost
 
@@ -25,7 +18,7 @@ configure<MavenPublishBaseExtension> {
     signAllPublications()
     publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
 
-    this.coordinates(project.group.toString(), project.name, project.version.toString())
+    coordinates(project.group.toString(), project.name, project.version.toString())
 
     pom {
         name.set("API Reference")

@@ -22,7 +22,8 @@ class FinchOkHttpClient private constructor() {
         @JvmStatic fun fromEnv(): FinchClient = builder().fromEnv().build()
     }
 
-    class Builder {
+    /** A builder for [FinchOkHttpClient]. */
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL

@@ -22,7 +22,8 @@ class FinchOkHttpClientAsync private constructor() {
         @JvmStatic fun fromEnv(): FinchClientAsync = builder().fromEnv().build()
     }
 
-    class Builder {
+    /** A builder for [FinchOkHttpClientAsync]. */
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL