release: 5.5.0

.github/workflows/ci.yml

@@ -1,18 +1,19 @@
 name: CI
 on:
   push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-      - next
+    branches-ignore:
+      - 'generated'
+      - 'codegen/**'
+      - 'integrated/**'
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
 
 jobs:
   lint:
     timeout-minutes: 10
     name: lint
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository == 'stainless-sdks/finch-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+
     steps:
       - uses: actions/checkout@v4
 
@@ -22,7 +23,7 @@ jobs:
           distribution: temurin
           java-version: |
             8
-            17
+            21
           cache: gradle
 
       - name: Set up Gradle
@@ -33,7 +34,7 @@ jobs:
   test:
     timeout-minutes: 10
     name: test
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository == 'stainless-sdks/finch-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
 
@@ -43,7 +44,7 @@ jobs:
           distribution: temurin
           java-version: |
             8
-            17
+            21
           cache: gradle
 
       - name: Set up Gradle

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.4.0"
+  ".": "5.5.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 45
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-a9dc15ba77c4c6e40c8f2429b1d614e7fe6888910579b54002fb90d418682d09.yml
-openapi_spec_hash: be98b11d320aa0a1f3443650ce1b5b90
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/finch%2Ffinch-05a1c7485ea6dd75ad2fb1a0628570d88a3e7c4f1e1ecad433711c78deae50e6.yml
+openapi_spec_hash: 6d6014d50e18c98219b496bb2a5dab1d
 config_hash: 53778a0b839c4f6ad34fbba051f5e8a6

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 5.5.0 (2025-04-23)
+
+Full Changelog: [v5.4.0...v5.5.0](https://github.com/Finch-API/finch-api-java/compare/v5.4.0...v5.5.0)
+
+### Features
+
+* **api:** api update ([8cdf256](https://github.com/Finch-API/finch-api-java/commit/8cdf256b5b9e96b4162b8baa3fc068cb510613e2))
+
+
+### Chores
+
+* **ci:** only use depot for staging repos ([415d708](https://github.com/Finch-API/finch-api-java/commit/415d708c3acfe3ab0b718e89178632d5952e261a))
+* **ci:** run on more branches and use depot runners ([876a6f9](https://github.com/Finch-API/finch-api-java/commit/876a6f9fb669c659dda8a349ba676545c5b78568))
+* **internal:** java 17 -> 21 on ci ([5982e36](https://github.com/Finch-API/finch-api-java/commit/5982e367891992a817ad418309b575ba207a04b5))
+
 ## 5.4.0 (2025-04-22)
 
 Full Changelog: [v5.3.0...v5.4.0](https://github.com/Finch-API/finch-api-java/compare/v5.3.0...v5.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/5.4.0)
-[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/5.4.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.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/5.5.0)
+[![javadoc](https://javadoc.io/badge2/com.tryfinch.api/finch-java/5.5.0/javadoc.svg)](https://javadoc.io/doc/com.tryfinch.api/finch-java/5.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/5.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/5.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:5.4.0")
+implementation("com.tryfinch.api:finch-java:5.5.0")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("com.tryfinch.api:finch-java:5.4.0")
 <dependency>
   <groupId>com.tryfinch.api</groupId>
   <artifactId>finch-java</artifactId>
-  <version>5.4.0</version>
+  <version>5.5.0</version>
 </dependency>
 ```
 

build.gradle.kts

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

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

@@ -11,6 +11,7 @@ import com.tryfinch.api.core.ExcludeMissing
 import com.tryfinch.api.core.JsonField
 import com.tryfinch.api.core.JsonMissing
 import com.tryfinch.api.core.JsonValue
+import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Collections
 import java.util.Objects
@@ -221,7 +222,7 @@ private constructor(
     class Attributes
     private constructor(
         private val employer: JsonField<Boolean>,
-        private val metadata: JsonValue,
+        private val metadata: JsonField<Metadata>,
         private val preTax: JsonField<Boolean>,
         private val type: JsonField<String>,
         private val additionalProperties: MutableMap<String, JsonValue>,
@@ -232,7 +233,9 @@ private constructor(
             @JsonProperty("employer")
             @ExcludeMissing
             employer: JsonField<Boolean> = JsonMissing.of(),
-            @JsonProperty("metadata") @ExcludeMissing metadata: JsonValue = JsonMissing.of(),
+            @JsonProperty("metadata")
+            @ExcludeMissing
+            metadata: JsonField<Metadata> = JsonMissing.of(),
             @JsonProperty("pre_tax") @ExcludeMissing preTax: JsonField<Boolean> = JsonMissing.of(),
             @JsonProperty("type") @ExcludeMissing type: JsonField<String> = JsonMissing.of(),
         ) : this(employer, metadata, preTax, type, mutableMapOf())
@@ -248,8 +251,11 @@ private constructor(
         /**
          * The metadata of the pay statement item derived by the rules engine if available. Each
          * attribute will be a key-value pair defined by a rule.
+         *
+         * @throws FinchInvalidDataException if the JSON field has an unexpected type (e.g. if the
+         *   server responded with an unexpected value).
          */
-        @JsonProperty("metadata") @ExcludeMissing fun _metadata(): JsonValue = metadata
+        fun metadata(): Optional<Metadata> = metadata.getOptional("metadata")
 
         /**
          * `true` if the pay statement item is pre-tax. This field is only available for employee
@@ -275,6 +281,13 @@ private constructor(
          */
         @JsonProperty("employer") @ExcludeMissing fun _employer(): JsonField<Boolean> = employer
 
+        /**
+         * Returns the raw JSON value of [metadata].
+         *
+         * Unlike [metadata], this method doesn't throw if the JSON field has an unexpected type.
+         */
+        @JsonProperty("metadata") @ExcludeMissing fun _metadata(): JsonField<Metadata> = metadata
+
         /**
          * Returns the raw JSON value of [preTax].
          *
@@ -311,7 +324,7 @@ private constructor(
         class Builder internal constructor() {
 
             private var employer: JsonField<Boolean> = JsonMissing.of()
-            private var metadata: JsonValue = JsonMissing.of()
+            private var metadata: JsonField<Metadata> = JsonMissing.of()
             private var preTax: JsonField<Boolean> = JsonMissing.of()
             private var type: JsonField<String> = JsonMissing.of()
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
@@ -354,7 +367,19 @@ private constructor(
              * The metadata of the pay statement item derived by the rules engine if available. Each
              * attribute will be a key-value pair defined by a rule.
              */
-            fun metadata(metadata: JsonValue) = apply { this.metadata = metadata }
+            fun metadata(metadata: Metadata?) = metadata(JsonField.ofNullable(metadata))
+
+            /** Alias for calling [Builder.metadata] with `metadata.orElse(null)`. */
+            fun metadata(metadata: Optional<Metadata>) = metadata(metadata.getOrNull())
+
+            /**
+             * Sets [Builder.metadata] to an arbitrary JSON value.
+             *
+             * You should usually call [Builder.metadata] with a well-typed [Metadata] value
+             * instead. This method is primarily for setting the field to an undocumented or not yet
+             * supported value.
+             */
+            fun metadata(metadata: JsonField<Metadata>) = apply { this.metadata = metadata }
 
             /**
              * `true` if the pay statement item is pre-tax. This field is only available for
@@ -432,6 +457,7 @@ private constructor(
             }
 
             employer()
+            metadata().ifPresent { it.validate() }
             preTax()
             type()
             validated = true
@@ -454,9 +480,118 @@ private constructor(
         @JvmSynthetic
         internal fun validity(): Int =
             (if (employer.asKnown().isPresent) 1 else 0) +
+                (metadata.asKnown().getOrNull()?.validity() ?: 0) +
                 (if (preTax.asKnown().isPresent) 1 else 0) +
                 (if (type.asKnown().isPresent) 1 else 0)
 
+        /**
+         * The metadata of the pay statement item derived by the rules engine if available. Each
+         * attribute will be a key-value pair defined by a rule.
+         */
+        class Metadata
+        @JsonCreator
+        private constructor(
+            @com.fasterxml.jackson.annotation.JsonValue
+            private val additionalProperties: Map<String, JsonValue>
+        ) {
+
+            @JsonAnyGetter
+            @ExcludeMissing
+            fun _additionalProperties(): Map<String, JsonValue> = additionalProperties
+
+            fun toBuilder() = Builder().from(this)
+
+            companion object {
+
+                /** Returns a mutable builder for constructing an instance of [Metadata]. */
+                @JvmStatic fun builder() = Builder()
+            }
+
+            /** A builder for [Metadata]. */
+            class Builder internal constructor() {
+
+                private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
+
+                @JvmSynthetic
+                internal fun from(metadata: Metadata) = apply {
+                    additionalProperties = metadata.additionalProperties.toMutableMap()
+                }
+
+                fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {
+                    this.additionalProperties.clear()
+                    putAllAdditionalProperties(additionalProperties)
+                }
+
+                fun putAdditionalProperty(key: String, value: JsonValue) = apply {
+                    additionalProperties.put(key, value)
+                }
+
+                fun putAllAdditionalProperties(additionalProperties: Map<String, JsonValue>) =
+                    apply {
+                        this.additionalProperties.putAll(additionalProperties)
+                    }
+
+                fun removeAdditionalProperty(key: String) = apply {
+                    additionalProperties.remove(key)
+                }
+
+                fun removeAllAdditionalProperties(keys: Set<String>) = apply {
+                    keys.forEach(::removeAdditionalProperty)
+                }
+
+                /**
+                 * Returns an immutable instance of [Metadata].
+                 *
+                 * Further updates to this [Builder] will not mutate the returned instance.
+                 */
+                fun build(): Metadata = Metadata(additionalProperties.toImmutable())
+            }
+
+            private var validated: Boolean = false
+
+            fun validate(): Metadata = apply {
+                if (validated) {
+                    return@apply
+                }
+
+                validated = true
+            }
+
+            fun isValid(): Boolean =
+                try {
+                    validate()
+                    true
+                } catch (e: FinchInvalidDataException) {
+                    false
+                }
+
+            /**
+             * Returns a score indicating how many valid values are contained in this object
+             * recursively.
+             *
+             * Used for best match union deserialization.
+             */
+            @JvmSynthetic
+            internal fun validity(): Int =
+                additionalProperties.count { (_, value) -> !value.isNull() && !value.isMissing() }
+
+            override fun equals(other: Any?): Boolean {
+                if (this === other) {
+                    return true
+                }
+
+                return /* spotless:off */ other is Metadata && additionalProperties == other.additionalProperties /* spotless:on */
+            }
+
+            /* spotless:off */
+            private val hashCode: Int by lazy { Objects.hash(additionalProperties) }
+            /* spotless:on */
+
+            override fun hashCode(): Int = hashCode
+
+            override fun toString() = "Metadata{additionalProperties=$additionalProperties}"
+        }
+
         override fun equals(other: Any?): Boolean {
             if (this === other) {
                 return true

finch-java-core/src/test/kotlin/com/tryfinch/api/models/HrisCompanyPayStatementItemListPageResponseTest.kt

@@ -19,7 +19,11 @@ internal class HrisCompanyPayStatementItemListPageResponseTest {
                         .attributes(
                             PayStatementItemListResponse.Attributes.builder()
                                 .employer(true)
-                                .metadata(JsonValue.from(mapOf<String, Any>()))
+                                .metadata(
+                                    PayStatementItemListResponse.Attributes.Metadata.builder()
+                                        .putAdditionalProperty("foo", JsonValue.from("bar"))
+                                        .build()
+                                )
                                 .preTax(true)
                                 .type("type")
                                 .build()
@@ -36,7 +40,11 @@ internal class HrisCompanyPayStatementItemListPageResponseTest {
                     .attributes(
                         PayStatementItemListResponse.Attributes.builder()
                             .employer(true)
-                            .metadata(JsonValue.from(mapOf<String, Any>()))
+                            .metadata(
+                                PayStatementItemListResponse.Attributes.Metadata.builder()
+                                    .putAdditionalProperty("foo", JsonValue.from("bar"))
+                                    .build()
+                            )
                             .preTax(true)
                             .type("type")
                             .build()
@@ -57,7 +65,11 @@ internal class HrisCompanyPayStatementItemListPageResponseTest {
                         .attributes(
                             PayStatementItemListResponse.Attributes.builder()
                                 .employer(true)
-                                .metadata(JsonValue.from(mapOf<String, Any>()))
+                                .metadata(
+                                    PayStatementItemListResponse.Attributes.Metadata.builder()
+                                        .putAdditionalProperty("foo", JsonValue.from("bar"))
+                                        .build()
+                                )
                                 .preTax(true)
                                 .type("type")
                                 .build()