From 090e27c96745e9b38b1b98d7eae870ff3ba72670 Mon Sep 17 00:00:00 2001
From: curfew-marathon <jakub.hertyk@auth0.com>
Date: Sun, 2 Aug 2026 11:28:59 -0400
Subject: [PATCH 1/2] fix: migrate transaction docs and examples to
 transactions() API

Move the write mode-selection Javadoc in OpenFgaClient and the example
projects off the double-negative disableTransactions(boolean) to the
affirmative transactions()/isTransactionsEnabled() API. Also switch the
internal write mode branch to !isTransactionsEnabled() so the SDK no longer
calls its own soon-to-be-deprecated method. Behavior is unchanged.

Test call sites that still use disableTransactions are intentionally left
for the deprecation issue, which will migrate them and keep one back-compat
test under @SuppressWarnings.

Refs #368
---
 .../main/java/dev/openfga/sdk/example/Example1.java    |  2 +-
 .../kotlin/dev/openfga/sdk/example/KotlinExample1.kt   |  2 +-
 .../java/dev/openfga/sdk/api/client/OpenFgaClient.java | 10 +++++-----
 .../java/dev/openfga/sdk/example/Example1.java         |  2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java b/examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java
index 97d0cfe0..8a2e27f6 100644
--- a/examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java
+++ b/examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java
@@ -117,7 +117,7 @@ public void run(String apiUrl) throws Exception {
                                         // relation
                                         )),
                         new ClientWriteOptions()
-                                .disableTransactions(true)
+                                .transactions(false)
                                 .authorizationModelId(authorizationModel.getAuthorizationModelId()))
                 .get();
         System.out.println("Done Writing Tuples");
diff --git a/examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt b/examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt
index 3e11bb3d..aeedb6bc 100644
--- a/examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt
+++ b/examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt
@@ -117,7 +117,7 @@ internal class KotlinExample1 {
                         )
                     ),
                 ClientWriteOptions()
-                    .disableTransactions(true)
+                    .transactions(false)
                     .authorizationModelId(authorizationModel.authorizationModelId)
             )
             .get()
diff --git a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
index 5d931ac7..6a6ba170 100644
--- a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
+++ b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
@@ -412,7 +412,7 @@ public CompletableFuture<ClientReadResponse> read(ClientReadRequest request, Cli
      * <p>This method can operate in two modes depending on the options provided:</p>
      *
      * <h3>Transactional Mode (default)</h3>
-     * <p>When {@code options.disableTransactions()} is false or not set:</p>
+     * <p>When {@code options.isTransactionsEnabled()} is true (the default):</p>
      * <ul>
      *   <li>All writes and deletes are executed as a single atomic transaction</li>
      *   <li>If any tuple fails, the entire operation fails and no changes are made</li>
@@ -421,7 +421,7 @@ public CompletableFuture<ClientReadResponse> read(ClientReadRequest request, Cli
      * </ul>
      *
      * <h3>Non-Transactional Mode</h3>
-     * <p>When {@code options.disableTransactions()} is true:</p>
+     * <p>When {@code options.isTransactionsEnabled()} is false:</p>
      * <ul>
      *   <li>Tuples are processed in chunks (size controlled by {@code transactionChunkSize})</li>
      *   <li>Each chunk is processed independently - some may succeed while others fail</li>
@@ -466,7 +466,7 @@ public CompletableFuture<ClientWriteResponse> write(ClientWriteRequest request)
      * <p>This method can operate in two modes depending on the options provided:</p>
      *
      * <h3>Transactional Mode (default)</h3>
-     * <p>When {@code options.disableTransactions()} is false or not set:</p>
+     * <p>When {@code options.isTransactionsEnabled()} is true (the default):</p>
      * <ul>
      *   <li>All writes and deletes are executed as a single atomic transaction</li>
      *   <li>If any tuple fails, the entire operation fails and no changes are made</li>
@@ -475,7 +475,7 @@ public CompletableFuture<ClientWriteResponse> write(ClientWriteRequest request)
      * </ul>
      *
      * <h3>Non-Transactional Mode</h3>
-     * <p>When {@code options.disableTransactions()} is true:</p>
+     * <p>When {@code options.isTransactionsEnabled()} is false:</p>
      * <ul>
      *   <li>Tuples are processed in chunks (size controlled by {@code transactionChunkSize})</li>
      *   <li>Each chunk is processed independently - some may succeed while others fail</li>
@@ -515,7 +515,7 @@ public CompletableFuture<ClientWriteResponse> write(ClientWriteRequest request,
         configuration.assertValid();
         String storeId = configuration.getStoreIdChecked();
 
-        if (options != null && options.disableTransactions()) {
+        if (options != null && !options.isTransactionsEnabled()) {
             return writeNonTransaction(storeId, request, options);
         }
 
diff --git a/src/test-integration/java/dev/openfga/sdk/example/Example1.java b/src/test-integration/java/dev/openfga/sdk/example/Example1.java
index 97d0cfe0..8a2e27f6 100644
--- a/src/test-integration/java/dev/openfga/sdk/example/Example1.java
+++ b/src/test-integration/java/dev/openfga/sdk/example/Example1.java
@@ -117,7 +117,7 @@ public void run(String apiUrl) throws Exception {
                                         // relation
                                         )),
                         new ClientWriteOptions()
-                                .disableTransactions(true)
+                                .transactions(false)
                                 .authorizationModelId(authorizationModel.getAuthorizationModelId()))
                 .get();
         System.out.println("Done Writing Tuples");

From 986a554bddd80b89a7f8d19c0b61a5870df210a2 Mon Sep 17 00:00:00 2001
From: curfew-marathon <jakub.hertyk@auth0.com>
Date: Sun, 2 Aug 2026 11:57:11 -0400
Subject: [PATCH 2/2] fix: clarify write mode Javadoc for the no-options
 overload

Address review feedback. The write(request) overload takes no options, so
describing the mode as options.isTransactionsEnabled() implied a call on an
absent or null options reference. Reword both overloads to key the mode off
the transactions() setter and state that transactional mode is the default
when no options are passed.

Docs only, no behavior change.

Refs #368
---
 .../java/dev/openfga/sdk/api/client/OpenFgaClient.java    | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
index 6a6ba170..daf96f11 100644
--- a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
+++ b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
@@ -412,7 +412,7 @@ public CompletableFuture<ClientReadResponse> read(ClientReadRequest request, Cli
      * <p>This method can operate in two modes depending on the options provided:</p>
      *
      * <h3>Transactional Mode (default)</h3>
-     * <p>When {@code options.isTransactionsEnabled()} is true (the default):</p>
+     * <p>Used by default, when no options are passed or when {@code transactions(true)} is set:</p>
      * <ul>
      *   <li>All writes and deletes are executed as a single atomic transaction</li>
      *   <li>If any tuple fails, the entire operation fails and no changes are made</li>
@@ -421,7 +421,7 @@ public CompletableFuture<ClientReadResponse> read(ClientReadRequest request, Cli
      * </ul>
      *
      * <h3>Non-Transactional Mode</h3>
-     * <p>When {@code options.isTransactionsEnabled()} is false:</p>
+     * <p>Used when {@code transactions(false)} is set on the options:</p>
      * <ul>
      *   <li>Tuples are processed in chunks (size controlled by {@code transactionChunkSize})</li>
      *   <li>Each chunk is processed independently - some may succeed while others fail</li>
@@ -466,7 +466,7 @@ public CompletableFuture<ClientWriteResponse> write(ClientWriteRequest request)
      * <p>This method can operate in two modes depending on the options provided:</p>
      *
      * <h3>Transactional Mode (default)</h3>
-     * <p>When {@code options.isTransactionsEnabled()} is true (the default):</p>
+     * <p>Used by default, when no options are passed or when {@code transactions(true)} is set:</p>
      * <ul>
      *   <li>All writes and deletes are executed as a single atomic transaction</li>
      *   <li>If any tuple fails, the entire operation fails and no changes are made</li>
@@ -475,7 +475,7 @@ public CompletableFuture<ClientWriteResponse> write(ClientWriteRequest request)
      * </ul>
      *
      * <h3>Non-Transactional Mode</h3>
-     * <p>When {@code options.isTransactionsEnabled()} is false:</p>
+     * <p>Used when {@code transactions(false)} is set on the options:</p>
      * <ul>
      *   <li>Tuples are processed in chunks (size controlled by {@code transactionChunkSize})</li>
      *   <li>Each chunk is processed independently - some may succeed while others fail</li>