release: 6.0.0

.github/workflows/ci.yml

@@ -17,9 +17,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Validate Gradle wrapper
-        uses: gradle/actions/wrapper-validation@v3
-
       - name: Set up Java
         uses: actions/setup-java@v4
         with:
@@ -30,7 +27,7 @@ jobs:
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/actions/setup-gradle@v4
 
       - name: Run lints
         run: ./scripts/lint

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.0.0"
+  ".": "6.0.0"
 }

CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 6.0.0 (2025-03-06)
+
+Full Changelog: [v5.0.0...v6.0.0](https://github.com/Modern-Treasury/modern-treasury-java/compare/v5.0.0...v6.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **client:** refactor multipart formdata impl ([#359](https://github.com/Modern-Treasury/modern-treasury-java/issues/359))
+
+### Features
+
+* **client:** accept `InputStream` and `Path` for file params ([#363](https://github.com/Modern-Treasury/modern-treasury-java/issues/363)) ([7873ac0](https://github.com/Modern-Treasury/modern-treasury-java/commit/7873ac0a31dacfb00090e15943149c9567dc8d08))
+* **client:** allow omitting params object when none required ([#350](https://github.com/Modern-Treasury/modern-treasury-java/issues/350)) ([8f75bcf](https://github.com/Modern-Treasury/modern-treasury-java/commit/8f75bcf3edfd416b8ba79caf5d9b1187a9bec82b))
+* **client:** get rid of annoying checked exceptions ([#345](https://github.com/Modern-Treasury/modern-treasury-java/issues/345)) ([f041471](https://github.com/Modern-Treasury/modern-treasury-java/commit/f041471e1aa9331193116beade1b9c8ecf1d092e))
+* **client:** support raw response access ([#358](https://github.com/Modern-Treasury/modern-treasury-java/issues/358)) ([56c91d6](https://github.com/Modern-Treasury/modern-treasury-java/commit/56c91d6de3622a365007df807502a25b772687e9))
+
+
+### Bug Fixes
+
+* **client:** add missing `@JvmStatic` ([#351](https://github.com/Modern-Treasury/modern-treasury-java/issues/351)) ([2580073](https://github.com/Modern-Treasury/modern-treasury-java/commit/25800731c8f5664f96f5dead9228bbcf89af30d2))
+* **client:** mark some request bodies as optional ([#347](https://github.com/Modern-Treasury/modern-treasury-java/issues/347)) ([46f9eac](https://github.com/Modern-Treasury/modern-treasury-java/commit/46f9eacd7e968a7d871a8b7a75acd1d4cc20ad86))
+
+
+### Chores
+
+* **ci:** update gradle actions to v4 ([#344](https://github.com/Modern-Treasury/modern-treasury-java/issues/344)) ([4477581](https://github.com/Modern-Treasury/modern-treasury-java/commit/447758145113d731e825a70813d2184f6edfafb8))
+* **client:** expose `Optional`, not nullable, from `ClientOptions` ([#362](https://github.com/Modern-Treasury/modern-treasury-java/issues/362)) ([b0b3f45](https://github.com/Modern-Treasury/modern-treasury-java/commit/b0b3f45a80c6cf6268e479f0fcf673f4719e9078))
+* **client:** refactor multipart formdata impl ([#359](https://github.com/Modern-Treasury/modern-treasury-java/issues/359)) ([bfcea00](https://github.com/Modern-Treasury/modern-treasury-java/commit/bfcea003d557f98c8c04a109e6d48985099199dd))
+* **client:** use deep identity methods for primitive array types ([#353](https://github.com/Modern-Treasury/modern-treasury-java/issues/353)) ([9dbeaf8](https://github.com/Modern-Treasury/modern-treasury-java/commit/9dbeaf8517d1a1437c7ff9fd5b31297586c98dca))
+* **docs:** add faq to readme ([#346](https://github.com/Modern-Treasury/modern-treasury-java/issues/346)) ([d1d4818](https://github.com/Modern-Treasury/modern-treasury-java/commit/d1d48185b2b216adfa7112629afa809be54ac295))
+* **internal:** add async service tests ([#352](https://github.com/Modern-Treasury/modern-treasury-java/issues/352)) ([27294e4](https://github.com/Modern-Treasury/modern-treasury-java/commit/27294e4a1c545e29db7fbbff258b4682c8fdcc1b))
+* **internal:** get rid of configuration cache ([#342](https://github.com/Modern-Treasury/modern-treasury-java/issues/342)) ([8acbd15](https://github.com/Modern-Treasury/modern-treasury-java/commit/8acbd15eef36035f8ae40262546c86e1ee10bae9))
+* **internal:** improve sync service tests ([27294e4](https://github.com/Modern-Treasury/modern-treasury-java/commit/27294e4a1c545e29db7fbbff258b4682c8fdcc1b))
+* **internal:** refactor `ErrorHandlingTest` ([#357](https://github.com/Modern-Treasury/modern-treasury-java/issues/357)) ([20a8d6a](https://github.com/Modern-Treasury/modern-treasury-java/commit/20a8d6ab0f2b12663111f6a42fcaeb6b6bd5b11b))
+* **internal:** refactor `ServiceParamsTest` ([#355](https://github.com/Modern-Treasury/modern-treasury-java/issues/355)) ([b942ac5](https://github.com/Modern-Treasury/modern-treasury-java/commit/b942ac58b14bc0c151a2cc0883fcb3e229cf9eb4))
+* **internal:** remove unnecessary non-null asserts in tests ([46f9eac](https://github.com/Modern-Treasury/modern-treasury-java/commit/46f9eacd7e968a7d871a8b7a75acd1d4cc20ad86))
+* **internal:** use `assertNotNull` in tests for type narrowing ([46f9eac](https://github.com/Modern-Treasury/modern-treasury-java/commit/46f9eacd7e968a7d871a8b7a75acd1d4cc20ad86))
+
+
+### Documentation
+
+* add immutability explanation to readme ([#348](https://github.com/Modern-Treasury/modern-treasury-java/issues/348)) ([8f6e885](https://github.com/Modern-Treasury/modern-treasury-java/commit/8f6e885f85b62780fa3863ca0e9426708ccfc00e))
+* add raw response readme documentation ([#360](https://github.com/Modern-Treasury/modern-treasury-java/issues/360)) ([40a2d03](https://github.com/Modern-Treasury/modern-treasury-java/commit/40a2d03ee0160be87104f4933084bc2acb8f0bab))
+* add source file links to readme ([#349](https://github.com/Modern-Treasury/modern-treasury-java/issues/349)) ([fe1facc](https://github.com/Modern-Treasury/modern-treasury-java/commit/fe1facc4f402f997f3f6129cd88d1cd6783141b5))
+* document file uploads in readme ([#364](https://github.com/Modern-Treasury/modern-treasury-java/issues/364)) ([bd71bc3](https://github.com/Modern-Treasury/modern-treasury-java/commit/bd71bc3dbd0ed5b26e8afa1be90cbef35c1024a2))
+* note required fields in `builder` javadoc ([#361](https://github.com/Modern-Treasury/modern-treasury-java/issues/361)) ([b791899](https://github.com/Modern-Treasury/modern-treasury-java/commit/b79189908fe67675950f723b7a7a49dba89ee461))
+* readme parameter tweaks ([27294e4](https://github.com/Modern-Treasury/modern-treasury-java/commit/27294e4a1c545e29db7fbbff258b4682c8fdcc1b))
+* update URLs from stainlessapi.com to stainless.com ([#356](https://github.com/Modern-Treasury/modern-treasury-java/issues/356)) ([08fb974](https://github.com/Modern-Treasury/modern-treasury-java/commit/08fb9744c4c5a732a9da7fb5124260188b1d041e))
+
 ## 5.0.0 (2025-02-19)
 
 Full Changelog: [v4.0.1...v5.0.0](https://github.com/Modern-Treasury/modern-treasury-java/compare/v4.0.1...v5.0.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.moderntreasury.api/modern-treasury-java)](https://central.sonatype.com/artifact/com.moderntreasury.api/modern-treasury-java/5.0.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.moderntreasury.api/modern-treasury-java)](https://central.sonatype.com/artifact/com.moderntreasury.api/modern-treasury-java/6.0.0)
 
 <!-- x-release-please-end -->
 
@@ -19,7 +19,7 @@ The REST API documentation can be found on [docs.moderntreasury.com](https://doc
 ### Gradle
 
 ```kotlin
-implementation("com.moderntreasury:modern-treasury-java:5.0.0")
+implementation("com.moderntreasury:modern-treasury-java:6.0.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("com.moderntreasury:modern-treasury-java:5.0.0")
 <dependency>
     <groupId>com.moderntreasury</groupId>
     <artifactId>modern-treasury-java</artifactId>
-    <version>5.0.0</version>
+    <version>6.0.0</version>
 </dependency>
 ```
 
@@ -110,6 +110,14 @@ To send a request to the Modern Treasury API, build an instance of some `Params`
 
 For example, `client.counterparties().create(...)` should be called with an instance of `CounterpartyCreateParams`, and it will return an instance of `Counterparty`.
 
+## Immutability
+
+Each class in the SDK has an associated [builder](https://blogs.oracle.com/javamagazine/post/exploring-joshua-blochs-builder-design-pattern-in-java) or factory method for constructing it.
+
+Each class is [immutable](https://docs.oracle.com/javase/tutorial/essential/concurrency/immutable.html) once constructed. If the class has an associated builder, then it has a `toBuilder()` method, which can be used to convert it back to a builder for making a modified copy.
+
+Because each class is immutable, builder modification will _never_ affect already built class instances.
+
 ## Asynchronous execution
 
 The default client is synchronous. To switch to asynchronous execution, call the `async()` method:
@@ -150,11 +158,108 @@ CompletableFuture<Counterparty> counterparty = client.counterparties().create(pa
 
 The asynchronous client supports the same options as the synchronous one, except most methods return `CompletableFuture`s.
 
+## File uploads
+
+The SDK defines methods that accept files.
+
+To upload a file, pass a [`Path`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/Path.html):
+
+```java
+import com.moderntreasury.api.models.Document;
+import com.moderntreasury.api.models.DocumentCreateParams;
+import java.nio.file.Paths;
+
+DocumentCreateParams params = DocumentCreateParams.builder()
+    .documentableId("24c6b7a3-02...")
+    .documentableType(DocumentCreateParams.DocumentableType.COUNTERPARTIES)
+    .file(Paths.get("my/file.txt"))
+    .build();
+Document document = client.documents().create(params);
+```
+
+Or an arbitrary [`InputStream`](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html):
+
+```java
+import com.moderntreasury.api.models.Document;
+import com.moderntreasury.api.models.DocumentCreateParams;
+import java.net.URL;
+
+DocumentCreateParams params = DocumentCreateParams.builder()
+    .documentableId("24c6b7a3-02...")
+    .documentableType(DocumentCreateParams.DocumentableType.COUNTERPARTIES)
+    .file(new URL("https://example.com").openStream())
+    .build();
+Document document = client.documents().create(params);
+```
+
+Or a `byte[]` array:
+
+```java
+import com.moderntreasury.api.models.Document;
+import com.moderntreasury.api.models.DocumentCreateParams;
+
+DocumentCreateParams params = DocumentCreateParams.builder()
+    .documentableId("24c6b7a3-02...")
+    .documentableType(DocumentCreateParams.DocumentableType.COUNTERPARTIES)
+    .file("content".getBytes())
+    .build();
+Document document = client.documents().create(params);
+```
+
+Note that when passing a non-`Path` its filename is unknown so it will not be included in the request. To manually set a filename, pass a `MultipartField`:
+
+```java
+import com.moderntreasury.api.core.MultipartField;
+import com.moderntreasury.api.models.Document;
+import com.moderntreasury.api.models.DocumentCreateParams;
+import java.io.InputStream;
+import java.net.URL;
+
+DocumentCreateParams params = DocumentCreateParams.builder()
+    .documentableId("24c6b7a3-02...")
+    .documentableType(DocumentCreateParams.DocumentableType.COUNTERPARTIES)
+    .file(MultipartField.<InputStream>builder()
+        .value(new URL("https://example.com").openStream())
+        .filename("my/file.txt")
+        .build())
+    .build();
+Document document = client.documents().create(params);
+```
+
+## Raw responses
+
+The SDK defines methods that deserialize responses into instances of Java classes. However, these methods don't provide access to the response headers, status code, or the raw response body.
+
+To access this data, prefix any HTTP method call on a client or service with `withRawResponse()`:
+
+```java
+import com.moderntreasury.api.core.http.Headers;
+import com.moderntreasury.api.core.http.HttpResponseFor;
+import com.moderntreasury.api.models.Counterparty;
+import com.moderntreasury.api.models.CounterpartyCreateParams;
+
+CounterpartyCreateParams params = CounterpartyCreateParams.builder()
+    .name("my first counterparty")
+    .build();
+HttpResponseFor<Counterparty> counterparty = client.counterparties().withRawResponse().create(params);
+
+int statusCode = counterparty.statusCode();
+Headers headers = counterparty.headers();
+```
+
+You can still deserialize the response into an instance of a Java class if needed:
+
+```java
+import com.moderntreasury.api.models.Counterparty;
+
+Counterparty parsedCounterparty = counterparty.parse();
+```
+
 ## Error handling
 
 The SDK throws custom unchecked exception types:
 
-- `ModernTreasuryServiceException`: Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
+- [`ModernTreasuryServiceException`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/errors/ModernTreasuryServiceException.kt): Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
 
   | Status | Exception                       |
   | ------ | ------------------------------- |
@@ -167,11 +272,11 @@ The SDK throws custom unchecked exception types:
   | 5xx    | `InternalServerException`       |
   | others | `UnexpectedStatusCodeException` |
 
-- `ModernTreasuryIoException`: I/O networking errors.
+- [`ModernTreasuryIoException`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/errors/ModernTreasuryIoException.kt): I/O networking errors.
 
-- `ModernTreasuryInvalidDataException`: 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.
+- [`ModernTreasuryInvalidDataException`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/errors/ModernTreasuryInvalidDataException.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.
 
-- `ModernTreasuryException`: 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.
+- [`ModernTreasuryException`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/errors/ModernTreasuryException.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.
 
 ## Pagination
 
@@ -338,7 +443,7 @@ CounterpartyCreateParams params = CounterpartyCreateParams.builder()
 
 These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods. You can also set undocumented parameters on nested headers, query params, or body classes using the `putAdditionalProperty` method. These properties can be accessed on the built object later using the `_additionalProperties()` method.
 
-To set a documented parameter or property to an undocumented or not yet supported _value_, pass a `JsonValue` object to its setter:
+To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/core/JsonValue.kt) object to its setter:
 
 ```java
 import com.moderntreasury.api.core.JsonValue;
@@ -407,7 +512,7 @@ if (name.isMissing()) {
 
 In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a `String`, but the API could return something else.
 
-By default, the SDK will not throw an exception in this case. It will throw `ModernTreasuryInvalidDataException` only if you directly access the property.
+By default, the SDK will not throw an exception in this case. It will throw [`ModernTreasuryInvalidDataException`](modern-treasury-java-core/src/main/kotlin/com/moderntreasury/api/errors/ModernTreasuryInvalidDataException.kt) only if you directly access the property.
 
 If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 
@@ -440,6 +545,35 @@ ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
     .build();
 ```
 
+## FAQ
+
+### Why don't you use plain `enum` classes?
+
+Java `enum` classes are not trivially [forwards compatible](https://www.stainless.com/blog/making-java-enums-forwards-compatible). Using them in the SDK could cause runtime exceptions if the API is updated to respond with a new enum value.
+
+### Why do you represent fields using `JsonField<T>` instead of just plain `T`?
+
+Using `JsonField<T>` enables a few features:
+
+- Allowing usage of [undocumented API functionality](#undocumented-api-functionality)
+- Lazily [validating the API response against the expected shape](#response-validation)
+- Representing absent vs explicitly null values
+
+### Why don't you use [`data` classes](https://kotlinlang.org/docs/data-classes.html)?
+
+It is not [backwards compatible to add new fields to a data class](https://kotlinlang.org/docs/api-guidelines-backward-compatibility.html#avoid-using-data-classes-in-your-api) and we don't want to introduce a breaking change every time we add a field to a class.
+
+### Why don't you use checked exceptions?
+
+Checked exceptions are widely considered a mistake in the Java programming language. In fact, they were omitted from Kotlin for this reason.
+
+Checked exceptions:
+
+- Are verbose to handle
+- Encourage error handling at the wrong level of abstraction, where nothing can be done about the error
+- Are tedious to propagate due to the [function coloring problem](https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function)
+- Don't play well with lambdas (also due to the function coloring problem)
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:

SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Reporting Security Issues
 
-This SDK is generated by [Stainless Software Inc](http://stainlessapi.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
 
-To report a security issue, please contact the Stainless team at security@stainlessapi.com.
+To report a security issue, please contact the Stainless team at security@stainless.com.
 
 ## Responsible Disclosure
 

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 allprojects {
     group = "com.moderntreasury"
-    version = "5.0.0" // x-release-please-version
+    version = "6.0.0" // x-release-please-version
 }
 
 nexusPublishing {

gradle.properties

@@ -1,4 +1,3 @@
-org.gradle.configuration-cache=true
 org.gradle.caching=true
 org.gradle.parallel=true
 org.gradle.daemon=false