release: 7.5.0

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ on:
 
 jobs:
   lint:
-    timeout-minutes: 10
+    timeout-minutes: 15
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/finch-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
@@ -37,7 +37,7 @@ jobs:
       - name: Run lints
         run: ./scripts/lint
   test:
-    timeout-minutes: 10
+    timeout-minutes: 15
     name: test
     runs-on: ${{ github.repository == 'stainless-sdks/finch-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork

.gitignore

@@ -2,6 +2,6 @@
 .gradle
 .idea
 .kotlin
-build
+build/
 codegen.log
 kls_database.db

.release-please-manifest.json

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

.stats.yml

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

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 7.5.0 (2025-08-14)
+
+Full Changelog: [v7.4.0...v7.5.0](https://github.com/Finch-API/finch-api-java/compare/v7.4.0...v7.5.0)
+
+### Features
+
+* add retryable exception ([451adb3](https://github.com/Finch-API/finch-api-java/commit/451adb3fea351e5e905f4f947b96ffb0692fc381))
+* **api:** api update ([e282b93](https://github.com/Finch-API/finch-api-java/commit/e282b93f4af685cb1f90e0d3f625992f2244fca7))
+* **api:** api update ([21029e1](https://github.com/Finch-API/finch-api-java/commit/21029e1962110fd6394a08af08b97ae39e784e79))
+* **client:** ensure compat with proguard ([56c3b0b](https://github.com/Finch-API/finch-api-java/commit/56c3b0bcad2cff10e9b412efe55230544214dfcd))
+
+
+### Bug Fixes
+
+* **client:** prioritise bearer auth ([3e8af3a](https://github.com/Finch-API/finch-api-java/commit/3e8af3ad0b7ba3f17f845da25205fcd12df9389e))
+* **client:** r8 support ([700fb08](https://github.com/Finch-API/finch-api-java/commit/700fb080718f1b339860b9e384f3f359a0e6290f))
+
+
+### Performance Improvements
+
+* **internal:** make formatting faster ([6c97cb5](https://github.com/Finch-API/finch-api-java/commit/6c97cb5e79daab075eb43efb35ab992baa011770))
+
+
+### Chores
+
+* **example:** fix run example comment ([316356f](https://github.com/Finch-API/finch-api-java/commit/316356fb19963ef6ef9698102f2f66ea7111d8be))
+* increase max gradle JVM heap to 8GB ([1eed053](https://github.com/Finch-API/finch-api-java/commit/1eed053bef23cc9aa82085af0d17c94adc63e225))
+* **internal:** add async lock helper ([290ee95](https://github.com/Finch-API/finch-api-java/commit/290ee954c5520a181678d8472e5849a42485b1ae))
+* **internal:** bump ci test timeout ([9e577c2](https://github.com/Finch-API/finch-api-java/commit/9e577c2f9c082d753abca9d7b2157f5dbc1d3536))
+* **internal:** dynamically determine included projects ([a9f3ad6](https://github.com/Finch-API/finch-api-java/commit/a9f3ad61141a729a69b5482e65537af3f247fe75))
+* **internal:** format identity methods ([fee1332](https://github.com/Finch-API/finch-api-java/commit/fee13320c0585e2ff8ac12e08de92619d81504e9))
+* **internal:** reduce proguard ci logging ([97228cc](https://github.com/Finch-API/finch-api-java/commit/97228cca761aa1e433639279102a592877e87dca))
+* **internal:** support passing arguments to test script ([ed21d5f](https://github.com/Finch-API/finch-api-java/commit/ed21d5f3060c72300e10783daa1845c2b05fb30b))
+* **internal:** update comment in script ([9a58acb](https://github.com/Finch-API/finch-api-java/commit/9a58acbb6d50ac2c08c2a00243fc547d8f6193fe))
+* update @stainless-api/prism-cli to v5.15.0 ([9338715](https://github.com/Finch-API/finch-api-java/commit/93387157cbd7f20a97e713952ae8eacd34a6129f))
+
 ## 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)

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.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)
+[![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.5.0)
+[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/7.5.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/7.5.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.4.0).
+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.5.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.4.0")
+implementation("com.tryfinch.api:finch-java:7.5.0")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("com.tryfinch.api:finch-java:7.4.0")
 <dependency>
   <groupId>com.tryfinch.api</groupId>
   <artifactId>finch-java</artifactId>
-  <version>7.4.0</version>
+  <version>7.5.0</version>
 </dependency>
 ```
 
@@ -235,6 +235,8 @@ The SDK throws custom unchecked exception types:
 
 - [`FinchIoException`](finch-java-core/src/main/kotlin/com/tryfinch/api/errors/FinchIoException.kt): I/O networking errors.
 
+- [`FinchRetryableException`](finch-java-core/src/main/kotlin/com/tryfinch/api/errors/FinchRetryableException.kt): Generic error indicating a failure that could be retried by the client.
+
 - [`FinchInvalidDataException`](finch-java-core/src/main/kotlin/com/tryfinch/api/errors/FinchInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
 
 - [`FinchException`](finch-java-core/src/main/kotlin/com/tryfinch/api/errors/FinchException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.
@@ -365,6 +367,12 @@ 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.
 
+## ProGuard and R8
+
+Although the SDK uses reflection, it is still usable with [ProGuard](https://github.com/Guardsquare/proguard) and [R8](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization) because `finch-java-core` is published with a [configuration file](finch-java-core/src/main/resources/META-INF/proguard/finch-java-core.pro) containing [keep rules](https://www.guardsquare.com/manual/configuration/usage).
+
+ProGuard and R8 should automatically detect and use the published rules, but you can also manually copy the keep rules if necessary.
+
 ## 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.

build.gradle.kts

@@ -8,7 +8,20 @@ repositories {
 
 allprojects {
     group = "com.tryfinch.api"
-    version = "7.4.0" // x-release-please-version
+    version = "7.5.0" // x-release-please-version
+}
+
+subprojects {
+    // These are populated with dependencies by `buildSrc` scripts.
+    tasks.register("format") {
+        group = "Verification"
+        description = "Formats all source files."
+    }
+    tasks.register("lint") {
+        group = "Verification"
+        description = "Verifies all source files are formatted."
+    }
+    apply(plugin = "org.jetbrains.dokka")
 }
 
 subprojects {

buildSrc/build.gradle.kts

@@ -10,7 +10,6 @@ repositories {
 }
 
 dependencies {
-    implementation("com.diffplug.spotless:spotless-plugin-gradle:7.0.2")
     implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20")
     implementation("com.vanniktech:gradle-maven-publish-plugin:0.28.0")
 }

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

@@ -1,24 +1,13 @@
-import com.diffplug.gradle.spotless.SpotlessExtension
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 
 plugins {
     `java-library`
-    id("com.diffplug.spotless")
 }
 
 repositories {
     mavenCentral()
 }
 
-configure<SpotlessExtension> {
-    java {
-        importOrder()
-        removeUnusedImports()
-        palantirJavaFormat()
-        toggleOffOn()
-    }
-}
-
 java {
     toolchain {
         languageVersion.set(JavaLanguageVersion.of(21))
@@ -53,3 +42,86 @@ tasks.withType<Test>().configureEach {
         exceptionFormat = TestExceptionFormat.FULL
     }
 }
+
+val palantir by configurations.creating
+dependencies {
+    palantir("com.palantir.javaformat:palantir-java-format:2.73.0")
+}
+
+fun registerPalantir(
+    name: String,
+    description: String,
+) {
+    val javaName = "${name}Java"
+    tasks.register<JavaExec>(javaName) {
+        group = "Verification"
+        this.description = description
+
+        classpath = palantir
+        mainClass = "com.palantir.javaformat.java.Main"
+
+        // Avoid an `IllegalAccessError` on Java 9+.
+        jvmArgs(
+            "--add-exports", "jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED",
+            "--add-exports", "jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED",
+            "--add-exports", "jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED",
+            "--add-exports", "jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED",
+            "--add-exports", "jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED",
+        )
+
+        // Use paths relative to the current module.
+        val argumentFile =
+            project.layout.buildDirectory.file("palantir-$name-args.txt").get().asFile
+        val lastRunTimeFile =
+            project.layout.buildDirectory.file("palantir-$name-last-run.txt").get().asFile
+
+        // Read the time when this task was last executed for this module (if ever).
+        val lastRunTime = lastRunTimeFile.takeIf { it.exists() }?.readText()?.toLongOrNull() ?: 0L
+
+        // Use a `fileTree` relative to the module's source directory.
+        val javaFiles = project.fileTree("src") { include("**/*.java") }
+
+        // Determine if any files need to be formatted or linted and continue only if there is at least
+        // one file.
+        onlyIf { javaFiles.any { it.lastModified() > lastRunTime } }
+
+        inputs.files(javaFiles)
+
+        doFirst {
+            // Create the argument file and set the preferred formatting style.
+            argumentFile.parentFile.mkdirs()
+            argumentFile.writeText("--palantir\n")
+
+            if (name == "lint") {
+                // For lint, do a dry run, so no files are modified. Set the exit code to 1 (instead of
+                // the default 0) if any files need to be formatted, indicating that linting has failed.
+                argumentFile.appendText("--dry-run\n")
+                argumentFile.appendText("--set-exit-if-changed\n")
+            } else {
+                // `--dry-run` and `--replace` (for in-place formatting) are mutually exclusive.
+                argumentFile.appendText("--replace\n")
+            }
+
+            // Write the modified files to the argument file.
+            javaFiles.filter { it.lastModified() > lastRunTime }
+                .forEach { argumentFile.appendText("${it.absolutePath}\n") }
+        }
+
+        doLast {
+            // Record the last execution time for later up-to-date checking.
+            lastRunTimeFile.writeText(System.currentTimeMillis().toString())
+        }
+
+        // Pass the argument file using the @ symbol
+        args = listOf("@${argumentFile.absolutePath}")
+
+        outputs.upToDateWhen { javaFiles.none { it.lastModified() > lastRunTime } }
+    }
+
+    tasks.named(name) {
+        dependsOn(tasks.named(javaName))
+    }
+}
+
+registerPalantir(name = "format", description = "Formats all Java source files.")
+registerPalantir(name = "lint", description = "Verifies all Java source files are formatted.")

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

@@ -1,4 +1,3 @@
-import com.diffplug.gradle.spotless.SpotlessExtension
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 
@@ -7,6 +6,10 @@ plugins {
     kotlin("jvm")
 }
 
+repositories {
+    mavenCentral()
+}
+
 kotlin {
     jvmToolchain {
         languageVersion.set(JavaLanguageVersion.of(21))
@@ -27,14 +30,77 @@ kotlin {
     }
 }
 
-configure<SpotlessExtension> {
-    kotlin {
-        ktfmt().kotlinlangStyle()
-        toggleOffOn()
-    }
-}
-
 tasks.withType<Test>().configureEach {
     systemProperty("junit.jupiter.execution.parallel.enabled", true)
     systemProperty("junit.jupiter.execution.parallel.mode.default", "concurrent")
 }
+
+val ktfmt by configurations.creating
+dependencies {
+    ktfmt("com.facebook:ktfmt:0.56")
+}
+
+fun registerKtfmt(
+    name: String,
+    description: String,
+) {
+    val kotlinName = "${name}Kotlin"
+    tasks.register<JavaExec>(kotlinName) {
+        group = "Verification"
+        this.description = description
+
+        classpath = ktfmt
+        mainClass = "com.facebook.ktfmt.cli.Main"
+
+        // Use paths relative to the current module.
+        val argumentFile = project.layout.buildDirectory.file("ktfmt-$name-args.txt").get().asFile
+        val lastRunTimeFile =
+            project.layout.buildDirectory.file("ktfmt-$name-last-run.txt").get().asFile
+
+        // Read the time when this task was last executed for this module (if ever).
+        val lastRunTime = lastRunTimeFile.takeIf { it.exists() }?.readText()?.toLongOrNull() ?: 0L
+
+        // Use a `fileTree` relative to the module's source directory.
+        val kotlinFiles = project.fileTree("src") { include("**/*.kt") }
+
+        // Determine if any files need to be formatted or linted and continue only if there is at least
+        // one file (otherwise Ktfmt will fail).
+        onlyIf { kotlinFiles.any { it.lastModified() > lastRunTime } }
+
+        inputs.files(kotlinFiles)
+
+        doFirst {
+            // Create the argument file and set the preferred formatting style.
+            argumentFile.parentFile.mkdirs()
+            argumentFile.writeText("--kotlinlang-style\n")
+
+            if (name == "lint") {
+                // For lint, do a dry run, so no files are modified. Set the exit code to 1 (instead of
+                // the default 0) if any files need to be formatted, indicating that linting has failed.
+                argumentFile.appendText("--dry-run\n")
+                argumentFile.appendText("--set-exit-if-changed\n")
+            }
+
+            // Write the modified files to the argument file.
+            kotlinFiles.filter { it.lastModified() > lastRunTime }
+                .forEach { argumentFile.appendText("${it.absolutePath}\n") }
+        }
+
+        doLast {
+            // Record the last execution time for later up-to-date checking.
+            lastRunTimeFile.writeText(System.currentTimeMillis().toString())
+        }
+
+        // Pass the argument file using the @ symbol
+        args = listOf("@${argumentFile.absolutePath}")
+
+        outputs.upToDateWhen { kotlinFiles.none { it.lastModified() > lastRunTime } }
+    }
+
+    tasks.named(name) {
+        dependsOn(tasks.named(kotlinName))
+    }
+}
+
+registerKtfmt(name = "format", description = "Formats all Kotlin source files.")
+registerKtfmt(name = "lint", description = "Verifies all Kotlin source files are formatted.")