fix: deprecate disableTransactions in favour of transactions() (#377)

* fix: deprecate disableTransactions in favour of transactions()

Re-apply @deprecated to both disableTransactions overloads with @deprecated
Javadoc pointing to transactions(boolean) and isTransactionsEnabled(), now that
the docs and examples teach the new API and it has shipped in 0.9.11.

Migrate the internal test call sites to transactions() so the build stays
warning-free, and add ClientWriteOptionsTest that intentionally exercises the
deprecated path under @SuppressWarnings, asserting disableTransactions remains
the exact inverse of transactions/isTransactionsEnabled.

Refs #369

* fix: apply spotless formatting to migrated test options

Collapse the two transactions(true).transactionChunkSize(1) statements onto a
single line to match palantir-java-format, as required by spotlessCheck.

Author: curfew-marathon

src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java

@@ -88,7 +88,12 @@ public boolean isTransactionsEnabled() {
      *
      * @param disableTransactions {@code true} to disable transactions, {@code false} to enable them
      * @return this {@code ClientWriteOptions} instance for method chaining
+     * @deprecated Use {@link #transactions(boolean)} instead. This method will be removed in a
+     *     future release. Replace {@code disableTransactions(true)} with
+     *     {@code transactions(false)}, and {@code disableTransactions(false)} with
+     *     {@code transactions(true)}.
      */
+    @Deprecated
     public ClientWriteOptions disableTransactions(boolean disableTransactions) {
         this.transactionsEnabled = !disableTransactions;
         return this;
@@ -98,7 +103,11 @@ public ClientWriteOptions disableTransactions(boolean disableTransactions) {
      * Returns whether transactions are disabled for write operations.
      *
      * @return {@code true} if transactions are disabled, {@code false} if enabled (default)
+     * @deprecated Use {@link #isTransactionsEnabled()} instead. This method will be removed in a
+     *     future release. Note that {@code isTransactionsEnabled()} returns the inverse of
+     *     this method.
      */
+    @Deprecated
     public boolean disableTransactions() {
         return !transactionsEnabled;
     }

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java

@@ -440,7 +440,7 @@ public void writeNonTransaction_withHeaders() throws Exception {
                         .user(DEFAULT_USER)));
         ClientWriteOptions options = new ClientWriteOptions()
                 .additionalHeaders(Map.of("test-header", "test-value-per-call"))
-                .disableTransactions(true);
+                .transactions(false);
 
         // When
         ClientWriteResponse response = fga.write(request, options).get();

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java

@@ -1285,7 +1285,7 @@ public void writeTest_nonTransaction() throws Exception {
                 .writes(List.of(writeTuple, writeTuple, writeTuple, writeTuple, writeTuple))
                 .deletes(List.of(tuple, tuple, tuple, tuple, tuple));
         ClientWriteOptions options =
-                new ClientWriteOptions().disableTransactions(true).transactionChunkSize(2);
+                new ClientWriteOptions().transactions(false).transactionChunkSize(2);
 
         // When
         var response = fga.write(request, options).get();
@@ -1353,7 +1353,7 @@ public void writeTest_nonTransactionsWithFailure() throws Exception {
                                 .condition(DEFAULT_CONDITION))
                         .collect(Collectors.toList()));
         ClientWriteOptions options =
-                new ClientWriteOptions().disableTransactions(true).transactionChunkSize(1);
+                new ClientWriteOptions().transactions(false).transactionChunkSize(1);
 
         // When
         ClientWriteResponse response = fga.write(request, options).get();
@@ -1429,8 +1429,7 @@ public void writeTest_transaction() throws Exception {
                 new ClientWriteRequest().writes(List.of(tuple, tuple, tuple)).deletes(List.of(tuple, tuple, tuple));
 
         // We expect transactionChunkSize will be ignored, and exactly one request will be sent.
-        ClientWriteOptions options =
-                new ClientWriteOptions().disableTransactions(false).transactionChunkSize(1);
+        ClientWriteOptions options = new ClientWriteOptions().transactions(true).transactionChunkSize(1);
 
         // When
         var response = fga.write(request, options).get();
@@ -1472,8 +1471,7 @@ public void writeTest_transactionWithFailure() {
                 new ClientWriteRequest().writes(List.of(tuple, tuple, tuple)).deletes(List.of(tuple, tuple, tuple));
 
         // We expect transactionChunkSize will be ignored, and exactly one request will be sent.
-        ClientWriteOptions options =
-                new ClientWriteOptions().disableTransactions(false).transactionChunkSize(1);
+        ClientWriteOptions options = new ClientWriteOptions().transactions(true).transactionChunkSize(1);
 
         // When
         var execException = assertThrows(
@@ -1683,7 +1681,7 @@ public void writeTest_nonTransaction_withConflictOptions() throws Exception {
         ClientWriteRequest request =
                 new ClientWriteRequest().writes(List.of(writeTuple)).deletes(List.of(deleteTuple));
         ClientWriteOptions options = new ClientWriteOptions()
-                .disableTransactions(true)
+                .transactions(false)
                 .onDuplicate(WriteRequestWrites.OnDuplicateEnum.IGNORE)
                 .onMissing(WriteRequestDeletes.OnMissingEnum.IGNORE);
 

src/test/java/dev/openfga/sdk/api/client/OpenFgaClientWriteResponseHeadersTest.java

@@ -172,7 +172,7 @@ void writeNonTransactionMode_shouldReturnEmptyHeaders() throws Exception {
                         .relation(DEFAULT_RELATION)
                         ._object(DEFAULT_OBJECT)));
 
-        ClientWriteOptions options = new ClientWriteOptions().disableTransactions(true);
+        ClientWriteOptions options = new ClientWriteOptions().transactions(false);
 
         // When
         ClientWriteResponse response = fgaClient.write(request, options).get();

src/test/java/dev/openfga/sdk/api/configuration/ClientWriteOptionsTest.java

@@ -0,0 +1,44 @@
+package dev.openfga.sdk.api.configuration;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+
+class ClientWriteOptionsTest {
+
+    @Test
+    void transactionsEnabledByDefault() {
+        ClientWriteOptions options = new ClientWriteOptions();
+
+        assertTrue(options.isTransactionsEnabled());
+    }
+
+    @Test
+    void transactionsFalseDisablesTransactions() {
+        ClientWriteOptions options = new ClientWriteOptions().transactions(false);
+
+        assertFalse(options.isTransactionsEnabled());
+    }
+
+    /**
+     * Covers the deprecated {@code disableTransactions} methods and asserts they remain the exact
+     * inverse of {@code transactions}/{@code isTransactionsEnabled}. This is the one place the
+     * deprecated path is exercised on purpose; the suppression keeps the rest of the build
+     * warning-free. Remove this test when the deprecated methods are removed.
+     */
+    @Test
+    @SuppressWarnings("deprecation")
+    void deprecatedDisableTransactionsRemainsInverseOfTransactions() {
+        // transactions(false) implies disableTransactions() == true
+        assertTrue(new ClientWriteOptions().transactions(false).disableTransactions());
+
+        // transactions(true) implies disableTransactions() == false
+        assertFalse(new ClientWriteOptions().transactions(true).disableTransactions());
+
+        // disableTransactions(true) implies isTransactionsEnabled() == false
+        assertFalse(new ClientWriteOptions().disableTransactions(true).isTransactionsEnabled());
+
+        // disableTransactions(false) implies isTransactionsEnabled() == true
+        assertTrue(new ClientWriteOptions().disableTransactions(false).isTransactionsEnabled());
+    }
+}