release: 2.0.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.12.0"
+  ".": "2.0.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 38
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-2526a31a361274411e6cfc64858b1b084a22ffb491a9490374b717534827b3e1.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-cf610d4dbb7e3d84161b5783a0861b2e551422eb5cf727dde86a839325d7ef76.yml

CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 2.0.0 (2024-12-19)
+
+Full Changelog: [v1.12.0...v2.0.0](https://github.com/Finch-API/finch-api-java/compare/v1.12.0...v2.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **client:** numeric enum member type ([#349](https://github.com/Finch-API/finch-api-java/issues/349))
+
+### Features
+
+* **api:** api update ([#348](https://github.com/Finch-API/finch-api-java/issues/348)) ([1f7f08f](https://github.com/Finch-API/finch-api-java/commit/1f7f08fdb0fac4043baa61ea2153529fad1fe8a1))
+* **api:** api update ([#350](https://github.com/Finch-API/finch-api-java/issues/350)) ([76486fd](https://github.com/Finch-API/finch-api-java/commit/76486fd74b4c69f1c1e758226877c50876e4e1dd))
+* **api:** api update ([#358](https://github.com/Finch-API/finch-api-java/issues/358)) ([aef03b5](https://github.com/Finch-API/finch-api-java/commit/aef03b5cab006660274c63214e6900a3659ab54d))
+* **api:** api update ([#363](https://github.com/Finch-API/finch-api-java/issues/363)) ([1f2e37b](https://github.com/Finch-API/finch-api-java/commit/1f2e37bd6728a70c0c3a5eb5ddf4485183ea30b7))
+
+
+### Bug Fixes
+
+* **client:** numeric enum member type ([#349](https://github.com/Finch-API/finch-api-java/issues/349)) ([7705d87](https://github.com/Finch-API/finch-api-java/commit/7705d87e122e0d06a8b88ac45ccca67a96521562))
+
+
+### Chores
+
+* **docs:** add example project ([#367](https://github.com/Finch-API/finch-api-java/issues/367)) ([7801ba2](https://github.com/Finch-API/finch-api-java/commit/7801ba2d49fc9131e28ac3c6aeffa719efaa1289))
+* **docs:** fix code block language ([#368](https://github.com/Finch-API/finch-api-java/issues/368)) ([723c35a](https://github.com/Finch-API/finch-api-java/commit/723c35a6b2f504bb3a480e0154537190515d0f1a))
+* **docs:** update readme ([#365](https://github.com/Finch-API/finch-api-java/issues/365)) ([fc4a2ac](https://github.com/Finch-API/finch-api-java/commit/fc4a2aceea8968037cc11a2300bdb2f3296d93d4))
+* **internal:** codegen related update ([#346](https://github.com/Finch-API/finch-api-java/issues/346)) ([90f7c99](https://github.com/Finch-API/finch-api-java/commit/90f7c993a426713f980b561f8ea0410f6e4079e5))
+* **internal:** codegen related update ([#355](https://github.com/Finch-API/finch-api-java/issues/355)) ([1a5d595](https://github.com/Finch-API/finch-api-java/commit/1a5d59579770cb25845c8047e43681aebf457480))
+* **internal:** remove unused and expand used wildcard imports ([#359](https://github.com/Finch-API/finch-api-java/issues/359)) ([c825267](https://github.com/Finch-API/finch-api-java/commit/c825267ecf91ac10db7738b6df7f350d4f36d390))
+* **internal:** remove unused and expand used wildcard imports ([#361](https://github.com/Finch-API/finch-api-java/issues/361)) ([3c80b52](https://github.com/Finch-API/finch-api-java/commit/3c80b52b83abfcce2f99cb3203b0008c02a35d0f))
+* **internal:** remove unused imports ([#354](https://github.com/Finch-API/finch-api-java/issues/354)) ([cddb901](https://github.com/Finch-API/finch-api-java/commit/cddb901f2e7ec7c266ee535511325ff753402384))
+* **test:** remove unused imports ([#356](https://github.com/Finch-API/finch-api-java/issues/356)) ([a313b58](https://github.com/Finch-API/finch-api-java/commit/a313b580708ec7885eb574610b84a1b139202bcf))
+* **test:** use `JsonValue` instead of `JsonString` ([#357](https://github.com/Finch-API/finch-api-java/issues/357)) ([d336f7d](https://github.com/Finch-API/finch-api-java/commit/d336f7d962bea0a56d89a553faf8cc2b1339556a))
+* update example values in tests and docs ([#351](https://github.com/Finch-API/finch-api-java/issues/351)) ([792f3f7](https://github.com/Finch-API/finch-api-java/commit/792f3f76ae6584f9f83924b4cbee31a6067a0b18))
+* update parameter examples in tests and docs ([#364](https://github.com/Finch-API/finch-api-java/issues/364)) ([5fb0cac](https://github.com/Finch-API/finch-api-java/commit/5fb0cac8da7fd4957fbaaacdbc8b46255740b6ce))
+
+
+### Styles
+
+* **internal:** make enum value definitions less verbose ([#352](https://github.com/Finch-API/finch-api-java/issues/352)) ([08a5c64](https://github.com/Finch-API/finch-api-java/commit/08a5c64440d627e115c0cd360675292cab9b53b5))
+* **internal:** move enum identity methods to bottom of class ([#353](https://github.com/Finch-API/finch-api-java/issues/353)) ([bd29c58](https://github.com/Finch-API/finch-api-java/commit/bd29c58c914b831560d94ad7cd60a3ae6cb79742))
+
 ## 1.12.0 (2024-11-27)
 
 Full Changelog: [v1.11.1...v1.12.0](https://github.com/Finch-API/finch-api-java/compare/v1.11.1...v1.12.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- 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/1.12.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/2.0.0)
 
 <!-- x-release-please-end -->
 
@@ -27,7 +27,7 @@ The REST API documentation can be found [in the Finch Documentation Center](htt
 <!-- x-release-please-start-version -->
 
 ```kotlin
-implementation("com.tryfinch.api:finch-java:1.12.0")
+implementation("com.tryfinch.api:finch-java:2.0.0")
 ```
 
 #### Maven
@@ -36,7 +36,7 @@ implementation("com.tryfinch.api:finch-java:1.12.0")
 <dependency>
     <groupId>com.tryfinch.api</groupId>
     <artifactId>finch-java</artifactId>
-    <version>1.12.0</version>
+    <version>2.0.0</version>
 </dependency>
 ```
 
@@ -49,6 +49,9 @@ Use `FinchOkHttpClient.builder()` to configure the client.
 Alternately, set the environment with `FINCH_CLIENT_ID`, `FINCH_CLIENT_SECRET` or `FINCH_WEBHOOK_SECRET`, and use `FinchOkHttpClient.fromEnv()` to read from the environment.
 
 ```java
+import com.tryfinch.api.client.FinchClient;
+import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
+
 FinchClient client = FinchOkHttpClient.fromEnv();
 
 // Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
@@ -70,13 +73,11 @@ Read the documentation for more configuration options.
 
 ### Example: creating a resource
 
-To create a new hris directory, first use the `HrisDirectoryListParams` builder to specify attributes,
-then pass that to the `list` method of the `directory` service.
+To create a new hris directory, first use the `HrisDirectoryListParams` builder to specify attributes, then pass that to the `list` method of the `directory` service.
 
 ```java
 import com.tryfinch.api.models.HrisDirectoryListPage;
 import com.tryfinch.api.models.HrisDirectoryListParams;
-import com.tryfinch.api.models.Page;
 
 HrisDirectoryListParams params = HrisDirectoryListParams.builder()
     .candidateId("<candidate id>")
@@ -86,19 +87,39 @@ HrisDirectoryListPage page = client.hris().directory().list(params);
 
 ### Example: listing resources
 
-The Finch API provides a `list` method to get a paginated list of directory.
-You can retrieve the first page by:
+The Finch API provides a `list` method to get a paginated list of directory. You can retrieve the first page by:
 
 ```java
+import com.tryfinch.api.models.HrisDirectoryListPage;
 import com.tryfinch.api.models.IndividualInDirectory;
-import com.tryfinch.api.models.Page;
 
 HrisDirectoryListPage page = client.hris().directory().list();
 for (IndividualInDirectory directory : page.individuals()) {
     System.out.println(directory);
 }
 ```
 
+Use the `HrisDirectoryListParams` builder to set parameters:
+
+```java
+import com.tryfinch.api.models.HrisDirectoryListPage;
+import com.tryfinch.api.models.HrisDirectoryListParams;
+
+HrisDirectoryListParams params = HrisDirectoryListParams.builder()
+    .limit(0L)
+    .offset(0L)
+    .build();
+HrisDirectoryListPage page1 = client.hris().directory().list(params);
+
+// Using the `from` method of the builder you can reuse previous params values:
+HrisDirectoryListPage page2 = client.hris().directory().list(HrisDirectoryListParams.builder()
+    .from(params)
+    .build());
+
+// Or easily get params for the next page by using the helper `getNextPageParams`:
+HrisDirectoryListPage page3 = client.hris().directory().list(params.getNextPageParams(page2));
+```
+
 See [Pagination](#pagination) below for more information on transparently working with lists of objects without worrying about fetching each page.
 
 ---
@@ -109,14 +130,14 @@ 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.
+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.
+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.models.core.JsonValue;
+import com.tryfinch.api.core.JsonValue;
+import com.tryfinch.api.models.HrisDirectoryListParams;
+
 HrisDirectoryListParams params = HrisDirectoryListParams.builder()
     // ... normal properties
     .putAdditionalProperty("secret_param", JsonValue.from("4242"))
@@ -130,15 +151,19 @@ HrisDirectoryListParams params = HrisDirectoryListParams.builder()
 When receiving a response, the Finch Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an unchecked `FinchInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model.
 
 ```java
+import com.tryfinch.api.models.HrisDirectoryListPage;
+
 HrisDirectoryListPage page = client.hris().directory().list().validate();
 ```
 
 ### Response properties as JSON
 
-In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by
-this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
+In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
 
 ```java
+import com.tryfinch.api.core.JsonField;
+import java.util.Optional;
+
 JsonField field = responseObj._field();
 
 if (field.isMissing()) {
@@ -160,24 +185,27 @@ if (field.isMissing()) {
 Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method:
 
 ```java
+import com.tryfinch.api.core.JsonValue;
+
 JsonValue secret = operationSupportMatrix._additionalProperties().get("secret_field");
 ```
 
 ---
 
 ## Pagination
 
-For methods that return a paginated list of results, this library provides convenient ways access
-the results either one page at a time, or item-by-item across all pages.
+For methods that return a paginated list of results, this library provides convenient ways access the results either one page at a time, or item-by-item across all pages.
 
 ### Auto-pagination
 
-To iterate through all results across all pages, you can use `autoPager`,
-which automatically handles fetching more pages for you:
+To iterate through all results across all pages, you can use `autoPager`, which automatically handles fetching more pages for you:
 
 ### Synchronous
 
 ```java
+import com.tryfinch.api.models.HrisDirectoryListPage;
+import com.tryfinch.api.models.IndividualInDirectory;
+
 // As an Iterable:
 HrisDirectoryListPage page = client.hris().directory().list(params);
 for (IndividualInDirectory directory : page.autoPager()) {
@@ -200,12 +228,12 @@ asyncClient.hris().directory().list(params).autoPager()
 
 ### Manual pagination
 
-If none of the above helpers meet your needs, you can also manually request pages one-by-one.
-A page of results has a `data()` method to fetch the list of objects, as well as top-level
-`response` and other methods to fetch top-level data about the page. It also has methods
-`hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
+If none of the above helpers meet your needs, you can also manually request pages one-by-one. A page of results has a `data()` method to fetch the list of objects, as well as top-level `response` and other methods to fetch top-level data about the page. It also has methods `hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
 
 ```java
+import com.tryfinch.api.models.HrisDirectoryListPage;
+import com.tryfinch.api.models.IndividualInDirectory;
+
 HrisDirectoryListPage page = client.hris().directory().list(params);
 while (page != null) {
     for (IndividualInDirectory directory : page.individuals()) {
@@ -238,31 +266,33 @@ This library throws exceptions in a single hierarchy for easy handling:
 
 - **`FinchException`** - Base exception for all exceptions
 
-  - **`FinchServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
+- **`FinchServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
 
-    | 400    | BadRequestException           |
-    | ------ | ----------------------------- |
-    | 401    | AuthenticationException       |
-    | 403    | PermissionDeniedException     |
-    | 404    | NotFoundException             |
-    | 422    | UnprocessableEntityException  |
-    | 429    | RateLimitException            |
-    | 5xx    | InternalServerException       |
-    | others | UnexpectedStatusCodeException |
+  | 400    | BadRequestException           |
+  | ------ | ----------------------------- |
+  | 401    | AuthenticationException       |
+  | 403    | PermissionDeniedException     |
+  | 404    | NotFoundException             |
+  | 422    | UnprocessableEntityException  |
+  | 429    | RateLimitException            |
+  | 5xx    | InternalServerException       |
+  | others | UnexpectedStatusCodeException |
 
-  - **`FinchIoException`** - I/O networking errors
-  - **`FinchInvalidDataException`** - any other exceptions on the client side, e.g.:
-    - We failed to serialize the request body
-    - We failed to parse the response body (has access to response code and body)
+- **`FinchIoException`** - I/O networking errors
+- **`FinchInvalidDataException`** - any other exceptions on the client side, e.g.:
+  - We failed to serialize the request body
+  - We failed to parse the response body (has access to response code and body)
 
 ## Network options
 
 ### Retries
 
-Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default.
-You can provide a `maxRetries` on the client builder to configure this:
+Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a `maxRetries` on the client builder to configure this:
 
 ```java
+import com.tryfinch.api.client.FinchClient;
+import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
+
 FinchClient client = FinchOkHttpClient.builder()
     .fromEnv()
     .maxRetries(4)
@@ -274,6 +304,10 @@ FinchClient client = FinchOkHttpClient.builder()
 Requests time out after 1 minute by default. You can configure this on the client builder:
 
 ```java
+import com.tryfinch.api.client.FinchClient;
+import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
+import java.time.Duration;
+
 FinchClient client = FinchOkHttpClient.builder()
     .fromEnv()
     .timeout(Duration.ofSeconds(30))
@@ -285,15 +319,36 @@ FinchClient client = FinchOkHttpClient.builder()
 Requests can be routed through a proxy. You can configure this on the client builder:
 
 ```java
+import com.tryfinch.api.client.FinchClient;
+import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
+import java.net.InetSocketAddress;
+import java.net.Proxy;
+
 FinchClient client = FinchOkHttpClient.builder()
     .fromEnv()
-    .proxy(new Proxy(
-        Type.HTTP,
-        new InetSocketAddress("proxy.com", 8080)
-    ))
+    .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("example.com", 8080)))
     .build();
 ```
 
+## Making custom/undocumented requests
+
+This library is typed for convenient access to the documented API. If you need to access undocumented params or response properties, the library can still be used.
+
+### Undocumented request params
+
+To make requests using undocumented parameters, you can provide or override parameters on the params object while building it.
+
+```java
+FooCreateParams address = FooCreateParams.builder()
+    .id("my_id")
+    .putAdditionalProperty("secret_prop", JsonValue.from("hello"))
+    .build();
+```
+
+### 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.
+
 ## Logging
 
 We use the standard [OkHttp logging interceptor](https://github.com/square/okhttp/tree/master/okhttp-logging-interceptor).

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 allprojects {
     group = "com.tryfinch.api"
-    version = "1.12.0" // x-release-please-version
+    version = "2.0.0" // x-release-please-version
 }
 
 

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

@@ -3,8 +3,16 @@
 package com.tryfinch.api.client
 
 import com.fasterxml.jackson.annotation.JsonProperty
-import com.tryfinch.api.models.*
-import com.tryfinch.api.services.blocking.*
+import com.tryfinch.api.services.blocking.AccessTokenService
+import com.tryfinch.api.services.blocking.AccountService
+import com.tryfinch.api.services.blocking.ConnectService
+import com.tryfinch.api.services.blocking.HrisService
+import com.tryfinch.api.services.blocking.JobService
+import com.tryfinch.api.services.blocking.PayrollService
+import com.tryfinch.api.services.blocking.ProviderService
+import com.tryfinch.api.services.blocking.RequestForwardingService
+import com.tryfinch.api.services.blocking.SandboxService
+import com.tryfinch.api.services.blocking.WebhookService
 
 interface FinchClient {