release: 7.4.0

.github/workflows/publish-sonatype.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: temurin
           java-version: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "7.3.1"
+  ".": "7.4.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 45
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-f7e741bc6e0175fd96a9db5348092b90a77b0985154c0814bb681ad5dccdf19a.yml
-openapi_spec_hash: b348a9ef407a8e91dd770fcb219d4ac5
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-73c284d36c1ed2d9963fc733e421005fad76e559de8efe9baa6511a43dd72668.yml
+openapi_spec_hash: 1e58c4445919b71c77e5c7f16bd6fa7d
 config_hash: 5146b12344dae76238940989dac1e8a0

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 7.4.0 (2025-07-24)
+
+Full Changelog: [v7.3.1...v7.4.0](https://github.com/Finch-API/finch-api-java/compare/v7.3.1...v7.4.0)
+
+### Features
+
+* **api:** api update ([f1f21d9](https://github.com/Finch-API/finch-api-java/commit/f1f21d90ad56582d33c0e1f8b7248cba3ccf381a))
+* **api:** api update ([21939b3](https://github.com/Finch-API/finch-api-java/commit/21939b3e793ae932cfe333a50e4996388900464f))
+* **client:** add `{QueryParams,Headers}#put(String, JsonValue)` methods ([c85d73a](https://github.com/Finch-API/finch-api-java/commit/c85d73ace557d4a52fadccbfca80ebf81a63c15d))
+* **client:** add https config options ([4ae1b1a](https://github.com/Finch-API/finch-api-java/commit/4ae1b1ad7b9ba3f76f027ae32e5bee6525706dd5))
+* **client:** allow configuring env via system properties ([acdb059](https://github.com/Finch-API/finch-api-java/commit/acdb059e62754399064125ff41c1d5a2ac1305ab))
+
+
+### Bug Fixes
+
+* **client:** accidental mutability of some classes ([f1e80c0](https://github.com/Finch-API/finch-api-java/commit/f1e80c04aca7aa069e3a653252705e1e32d3d018))
+* **client:** ensure error handling always occurs ([98e72bc](https://github.com/Finch-API/finch-api-java/commit/98e72bc3ee2085f94175a8326f2bc75c11dca281))
+* **internal:** fix error handlers on ClientImpl ([8cfda8e](https://github.com/Finch-API/finch-api-java/commit/8cfda8eb135f79e051f882b23eeb61e18367da5b))
+* use errorHandler ([f1f1119](https://github.com/Finch-API/finch-api-java/commit/f1f11199de44aa3277553ffdfa35715e966bc13c))
+
+
+### Chores
+
+* **ci:** bump `actions/setup-java` to v4 ([a15c7b6](https://github.com/Finch-API/finch-api-java/commit/a15c7b62eedd8278ea6f4cc65dc1211b3d2c92da))
+* **internal:** allow running specific example from cli ([c1eebc5](https://github.com/Finch-API/finch-api-java/commit/c1eebc5989312477b4c60d26e21e7b59e43a6c1d))
+* **internal:** refactor delegating from client to options ([e9e1c40](https://github.com/Finch-API/finch-api-java/commit/e9e1c400440734ec210fc759149de5b014102d11))
+* **internal:** remove unnecessary `[...]` in `[@see](https://github.com/see)` ([8b2df3c](https://github.com/Finch-API/finch-api-java/commit/8b2df3cab95afc11b9275bbce043a7ba061a1c26))
+
+
+### Documentation
+
+* fix missing readme comment ([32795c6](https://github.com/Finch-API/finch-api-java/commit/32795c657795d4855a237d88ef8509cd6c420aee))
+* more code comments ([7e48fcf](https://github.com/Finch-API/finch-api-java/commit/7e48fcff3d3c3a80fae1585250d7ae9767a8cea7))
+
 ## 7.3.1 (2025-07-08)
 
 Full Changelog: [v7.3.0...v7.3.1](https://github.com/Finch-API/finch-api-java/compare/v7.3.0...v7.3.1)

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/7.3.1)
-[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/7.3.1/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/7.3.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-java)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-java/7.4.0)
+[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/7.4.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/7.4.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 available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-java/7.3.1).
+The REST API documentation can be found on [developer.tryfinch.com](https://developer.tryfinch.com/). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-java/7.4.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:7.3.1")
+implementation("com.tryfinch.api:finch-java:7.4.0")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("com.tryfinch.api:finch-java:7.3.1")
 <dependency>
   <groupId>com.tryfinch.api</groupId>
   <artifactId>finch-java</artifactId>
-  <version>7.3.1</version>
+  <version>7.4.0</version>
 </dependency>
 ```
 
@@ -54,7 +54,8 @@ 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`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
+    // Configures using the `finch.clientId`, `finch.clientSecret`, `finch.webhookSecret` and `finch.baseUrl` system properties
+    // Or configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -64,14 +65,15 @@ HrisDirectoryListPage page = client.hris().directory().list();
 
 ## Client configuration
 
-Configure the client using environment variables:
+Configure the client using system properties or environment variables:
 
 ```java
 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`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
+    // Configures using the `finch.clientId`, `finch.clientSecret`, `finch.webhookSecret` and `finch.baseUrl` system properties
+    // Or 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,20 +97,23 @@ 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`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
+    // Configures using the `finch.clientId`, `finch.clientSecret`, `finch.webhookSecret` and `finch.baseUrl` system properties
+    // Or 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    | -                            |
-| `baseUrl`       | `FINCH_BASE_URL`       | true     | `"https://api.tryfinch.com"` |
+| Setter          | System property       | Environment variable   | Required | Default value                |
+| --------------- | --------------------- | ---------------------- | -------- | ---------------------------- |
+| `clientId`      | `finch.clientId`      | `FINCH_CLIENT_ID`      | false    | -                            |
+| `clientSecret`  | `finch.clientSecret`  | `FINCH_CLIENT_SECRET`  | false    | -                            |
+| `webhookSecret` | `finch.webhookSecret` | `FINCH_WEBHOOK_SECRET` | false    | -                            |
+| `baseUrl`       | `finch.baseUrl`       | `FINCH_BASE_URL`       | true     | `"https://api.tryfinch.com"` |
+
+System properties take precedence over environment variables.
 
 > [!TIP]
 > Don't create more than one client in the same application. Each client has a connection pool and
@@ -155,7 +160,8 @@ import com.tryfinch.api.models.HrisDirectoryListParams;
 import java.util.concurrent.CompletableFuture;
 
 FinchClient client = FinchOkHttpClient.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
+    // Configures using the `finch.clientId`, `finch.clientSecret`, `finch.webhookSecret` and `finch.baseUrl` system properties
+    // Or configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -173,7 +179,8 @@ import com.tryfinch.api.models.HrisDirectoryListParams;
 import java.util.concurrent.CompletableFuture;
 
 FinchClientAsync client = FinchOkHttpClientAsync.builder()
-    // Configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
+    // Configures using the `finch.clientId`, `finch.clientSecret`, `finch.webhookSecret` and `finch.baseUrl` system properties
+    // Or configures using the `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET`, `FINCH_WEBHOOK_SECRET` and `FINCH_BASE_URL` environment variables
     .fromEnv()
     .accessToken("My Access Token")
     .build();
@@ -373,7 +380,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:
 
@@ -383,7 +390,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:
 
@@ -445,6 +452,28 @@ FinchClient client = FinchOkHttpClient.builder()
     .build();
 ```
 
+### HTTPS
+
+> [!NOTE]
+> Most applications should not call these methods, and instead use the system defaults. The defaults include
+> special optimizations that can be lost if the implementations are modified.
+
+To configure how HTTPS connections are secured, configure the client using the `sslSocketFactory`, `trustManager`, and `hostnameVerifier` methods:
+
+```java
+import com.tryfinch.api.client.FinchClient;
+import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
+
+FinchClient client = FinchOkHttpClient.builder()
+    .fromEnv()
+    // If `sslSocketFactory` is set, then `trustManager` must be set, and vice versa.
+    .sslSocketFactory(yourSSLSocketFactory)
+    .trustManager(yourTrustManager)
+    .hostnameVerifier(yourHostnameVerifier)
+    .accessToken("My Access Token")
+    .build();
+```
+
 ### Custom HTTP client
 
 The SDK consists of three artifacts:

build.gradle.kts

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