release: 5.3.0 (#466)

* docs: update documentation links to be more uniform

* docs(client): update jackson compat error message

* docs: explain jackson compat in readme

* perf(internal): improve compilation+test speed

* docs: explain http client customization

* feat(api): api update

* codegen metadata

* release: 5.3.0

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.github/workflows/publish-sonatype.yml

@@ -33,7 +33,7 @@ jobs:
           export -- GPG_SIGNING_KEY_ID
           printenv -- GPG_SIGNING_KEY | gpg --batch --passphrase-fd 3 --import 3<<< "$GPG_SIGNING_PASSWORD"
           GPG_SIGNING_KEY_ID="$(gpg --with-colons --list-keys | awk -F : -- '/^pub:/ { getline; print "0x" substr($10, length($10) - 7) }')"
-          ./gradlew publishAndReleaseToMavenCentral --stacktrace -PmavenCentralUsername="$SONATYPE_USERNAME" -PmavenCentralPassword="$SONATYPE_PASSWORD"
+          ./gradlew publishAndReleaseToMavenCentral --stacktrace -PmavenCentralUsername="$SONATYPE_USERNAME" -PmavenCentralPassword="$SONATYPE_PASSWORD" --no-configuration-cache
         env:
           SONATYPE_USERNAME: ${{ secrets.FINCH_SONATYPE_USERNAME || secrets.SONATYPE_USERNAME }}
           SONATYPE_PASSWORD: ${{ secrets.FINCH_SONATYPE_PASSWORD || secrets.SONATYPE_PASSWORD }}

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.2.0"
+  ".": "5.3.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 45
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-ff61a38530dfae03860bceb49379e84bfc7434eeb5d2f1dc9677cb162014faf1.yml
-openapi_spec_hash: df3bdaf4acf575bb07767cae7ca24d69
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-46640c1b468813b828be61b1af5cb5450f9555c4c757c5a740189906a8d56672.yml
+openapi_spec_hash: 1d5845ae61d2c0a143db43d579b048c5
 config_hash: 53778a0b839c4f6ad34fbba051f5e8a6

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 5.3.0 (2025-04-18)
+
+Full Changelog: [v5.2.0...v5.3.0](https://github.com/Finch-API/finch-api-kotlin/compare/v5.2.0...v5.3.0)
+
+### Features
+
+* **api:** api update ([925bbef](https://github.com/Finch-API/finch-api-kotlin/commit/925bbef7b02aa1491f2a74cf773272c9ae2a03ad))
+
+
+### Performance Improvements
+
+* **internal:** improve compilation+test speed ([d02a977](https://github.com/Finch-API/finch-api-kotlin/commit/d02a9774127d594c1298887d5a3a559588772114))
+
+
+### Documentation
+
+* **client:** update jackson compat error message ([7ed0ef6](https://github.com/Finch-API/finch-api-kotlin/commit/7ed0ef6f37865422c4106ac2522462acca655909))
+* explain http client customization ([56d4a3e](https://github.com/Finch-API/finch-api-kotlin/commit/56d4a3e3613e8c7610153df6c17dcc7adf168faa))
+* explain jackson compat in readme ([a398943](https://github.com/Finch-API/finch-api-kotlin/commit/a3989439c70f8d2fd9b0b627e11ed77f59403243))
+* update documentation links to be more uniform ([362f869](https://github.com/Finch-API/finch-api-kotlin/commit/362f869d455eeebc71b5bf2d772a1a37d1221ce5))
+
 ## 5.2.0 (2025-04-12)
 
 Full Changelog: [v5.1.0...v5.2.0](https://github.com/Finch-API/finch-api-kotlin/compare/v5.1.0...v5.2.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-kotlin)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-kotlin/5.2.0)
-[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-kotlin/5.2.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-kotlin/5.2.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.tryfinch.api/finch-kotlin)](https://central.sonatype.com/artifact/com.tryfinch.api/finch-kotlin/5.3.0)
+[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-kotlin/5.3.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-kotlin/5.3.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/). KDocs are also available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-kotlin/5.2.0).
+The REST API documentation can be found on [developer.tryfinch.com](https://developer.tryfinch.com/). KDocs are available on [javadoc.io](https://javadoc.io/doc/com.tryfinch.api/finch-kotlin/5.3.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-kotlin:5.2.0")
+implementation("com.tryfinch.api:finch-kotlin:5.3.0")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("com.tryfinch.api:finch-kotlin:5.2.0")
 <dependency>
   <groupId>com.tryfinch.api</groupId>
   <artifactId>finch-kotlin</artifactId>
-  <version>5.2.0</version>
+  <version>5.3.0</version>
 </dependency>
 ```
 
@@ -288,6 +288,17 @@ both of which will raise an error if the signature is invalid.
 Note that the "body" parameter must be the raw JSON string sent from the server (do not parse it first).
 The `.unwrap()` method can parse this JSON for you.
 
+## Jackson
+
+The SDK depends on [Jackson](https://github.com/FasterXML/jackson) for JSON serialization/deserialization. It is compatible with version 2.13.4 or higher, but depends on version 2.18.2 by default.
+
+The SDK throws an exception if it detects an incompatible Jackson version at runtime (e.g. if the default version was overridden in your Maven or Gradle config).
+
+If the SDK threw an exception, but you're _certain_ the version is compatible, then disable the version check using the `checkJacksonVersionCompatibility` on [`FinchOkHttpClient`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt) or [`FinchOkHttpClientAsync`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt).
+
+> [!CAUTION]
+> We make no guarantee that the SDK works correctly when the Jackson version check is disabled.
+
 ## Network options
 
 ### Retries
@@ -365,6 +376,42 @@ val client: FinchClient = FinchOkHttpClient.builder()
     .build()
 ```
 
+### Custom HTTP client
+
+The SDK consists of three artifacts:
+
+- `finch-kotlin-core`
+  - Contains core SDK logic
+  - Does not depend on [OkHttp](https://square.github.io/okhttp)
+  - Exposes [`FinchClient`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClient.kt), [`FinchClientAsync`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientAsync.kt), [`FinchClientImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientImpl.kt), and [`FinchClientAsyncImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientAsyncImpl.kt), all of which can work with any HTTP client
+- `finch-kotlin-client-okhttp`
+  - Depends on [OkHttp](https://square.github.io/okhttp)
+  - Exposes [`FinchOkHttpClient`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt) and [`FinchOkHttpClientAsync`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt), which provide a way to construct [`FinchClientImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientImpl.kt) and [`FinchClientAsyncImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientAsyncImpl.kt), respectively, using OkHttp
+- `finch-kotlin`
+  - Depends on and exposes the APIs of both `finch-kotlin-core` and `finch-kotlin-client-okhttp`
+  - Does not have its own logic
+
+This structure allows replacing the SDK's default HTTP client without pulling in unnecessary dependencies.
+
+#### Customized [`OkHttpClient`](https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.html)
+
+> [!TIP]
+> Try the available [network options](#network-options) before replacing the default client.
+
+To use a customized `OkHttpClient`:
+
+1. Replace your [`finch-kotlin` dependency](#installation) with `finch-kotlin-core`
+2. Copy `finch-kotlin-client-okhttp`'s [`OkHttpClient`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/OkHttpClient.kt) class into your code and customize it
+3. Construct [`FinchClientImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientImpl.kt) or [`FinchClientAsyncImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientAsyncImpl.kt), similarly to [`FinchOkHttpClient`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt) or [`FinchOkHttpClientAsync`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt), using your customized client
+
+### Completely custom HTTP client
+
+To use a completely custom HTTP client:
+
+1. Replace your [`finch-kotlin` dependency](#installation) with `finch-kotlin-core`
+2. Write a class that implements the [`HttpClient`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/core/http/HttpClient.kt) interface
+3. Construct [`FinchClientImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientImpl.kt) or [`FinchClientAsyncImpl`](finch-kotlin-core/src/main/kotlin/com/tryfinch/api/client/FinchClientAsyncImpl.kt), similarly to [`FinchOkHttpClient`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt) or [`FinchOkHttpClientAsync`](finch-kotlin-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt), using your new client class
+
 ## Undocumented API functionality
 
 The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.

build.gradle.kts

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

buildSrc/src/main/kotlin/finch.kotlin.gradle.kts

@@ -9,7 +9,7 @@ plugins {
 
 kotlin {
     jvmToolchain {
-        languageVersion.set(JavaLanguageVersion.of(17))
+        languageVersion.set(JavaLanguageVersion.of(21))
     }
 
     compilerOptions {
@@ -19,6 +19,8 @@ kotlin {
             // Suppress deprecation warnings because we may still reference and test deprecated members.
             // TODO: Replace with `-Xsuppress-warning=DEPRECATION` once we use Kotlin compiler 2.1.0+.
             "-nowarn",
+            // Use as many threads as there are CPU cores on the machine for compilation.
+            "-Xbackend-threads=0",
         )
         jvmTarget.set(JvmTarget.JVM_1_8)
         languageVersion.set(KotlinVersion.KOTLIN_1_8)
@@ -34,8 +36,7 @@ configure<SpotlessExtension> {
     }
 }
 
-// Run tests in parallel to some degree.
 tasks.withType<Test>().configureEach {
-    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
-    forkEvery = 100
+    systemProperty("junit.jupiter.execution.parallel.enabled", true)
+    systemProperty("junit.jupiter.execution.parallel.mode.default", "concurrent")
 }

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

@@ -52,7 +52,7 @@ internal fun checkJacksonVersionCompatibility() {
         }
     check(incompatibleJacksonVersions.isEmpty()) {
         """
-This SDK depends on Jackson version $MINIMUM_JACKSON_VERSION, but the following incompatible Jackson versions were detected at runtime:
+This SDK requires a minimum Jackson version of $MINIMUM_JACKSON_VERSION, but the following incompatible Jackson versions were detected at runtime:
 
 ${incompatibleJacksonVersions.asSequence().map { (version, incompatibilityReason) ->
     "- `${version.toFullString().replace("/", ":")}` ($incompatibilityReason)"
@@ -63,6 +63,8 @@ This can happen if you are either:
 2. Depending on some library that depends on different Jackson versions, potentially transitively
 
 Double-check that you are depending on compatible Jackson versions.
+
+See https://www.github.com/Finch-API/finch-api-kotlin#jackson for more information.
         """
             .trimIndent()
     }

finch-kotlin-core/src/main/kotlin/com/tryfinch/api/core/http/RetryingHttpClient.kt

@@ -21,6 +21,7 @@ import kotlinx.coroutines.delay
 class RetryingHttpClient
 private constructor(
     private val httpClient: HttpClient,
+    private val sleeper: Sleeper,
     private val clock: Clock,
     private val maxRetries: Int,
     private val idempotencyHeader: String?,
@@ -60,10 +61,10 @@ private constructor(
                     null
                 }
 
-            val backoffMillis = getRetryBackoffMillis(retries, response)
+            val backoffDuration = getRetryBackoffDuration(retries, response)
             // All responses must be closed, so close the failed one before retrying.
             response?.close()
-            Thread.sleep(backoffMillis.toMillis())
+            sleeper.sleep(backoffDuration)
         }
     }
 
@@ -104,10 +105,10 @@ private constructor(
                     null
                 }
 
-            val backoffMillis = getRetryBackoffMillis(retries, response)
+            val backoffDuration = getRetryBackoffDuration(retries, response)
             // All responses must be closed, so close the failed one before retrying.
             response?.close()
-            delay(backoffMillis.toKotlinDuration())
+            sleeper.sleepAsync(backoffDuration)
         }
     }
 
@@ -162,7 +163,7 @@ private constructor(
         // retried.
         throwable is IOException || throwable is FinchIoException
 
-    private fun getRetryBackoffMillis(retries: Int, response: HttpResponse?): Duration {
+    private fun getRetryBackoffDuration(retries: Int, response: HttpResponse?): Duration {
         // About the Retry-After header:
         // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
         response
@@ -215,12 +216,22 @@ private constructor(
     class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
+        private var sleeper: Sleeper =
+            object : Sleeper {
+
+                override fun sleep(duration: Duration) = Thread.sleep(duration.toMillis())
+
+                override suspend fun sleepAsync(duration: Duration) =
+                    delay(duration.toKotlinDuration())
+            }
         private var clock: Clock = Clock.systemUTC()
         private var maxRetries: Int = 2
         private var idempotencyHeader: String? = null
 
         fun httpClient(httpClient: HttpClient) = apply { this.httpClient = httpClient }
 
+        internal fun sleeper(sleeper: Sleeper) = apply { this.sleeper = sleeper }
+
         fun clock(clock: Clock) = apply { this.clock = clock }
 
         fun maxRetries(maxRetries: Int) = apply { this.maxRetries = maxRetries }
@@ -230,9 +241,17 @@ private constructor(
         fun build(): HttpClient =
             RetryingHttpClient(
                 checkRequired("httpClient", httpClient),
+                sleeper,
                 clock,
                 maxRetries,
                 idempotencyHeader,
             )
     }
+
+    internal interface Sleeper {
+
+        fun sleep(duration: Duration)
+
+        suspend fun sleepAsync(duration: Duration)
+    }
 }

finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/Company.kt

@@ -129,7 +129,8 @@ private constructor(
     fun primaryEmail(): String? = primaryEmail.getNullable("primary_email")
 
     /**
-     * The phone number of the main administrator on the account. Format: `XXXXXXXXXX`
+     * The phone number of the main administrator on the account. Format: E.164, with extension
+     * where applicable, e.g. `+NNNNNNNNNNN xExtension`
      *
      * @throws FinchInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -405,7 +406,10 @@ private constructor(
             this.primaryEmail = primaryEmail
         }
 
-        /** The phone number of the main administrator on the account. Format: `XXXXXXXXXX` */
+        /**
+         * The phone number of the main administrator on the account. Format: E.164, with extension
+         * where applicable, e.g. `+NNNNNNNNNNN xExtension`
+         */
         fun primaryPhoneNumber(primaryPhoneNumber: String?) =
             primaryPhoneNumber(JsonField.ofNullable(primaryPhoneNumber))