[CHA-1703] Add Future Channel Bans support (#229)

* feat: [CHA-1699] add Future Channel Bans support

- Add banFromFutureChannels field to UserBanRequestData
- Add removeFutureChannelsBan method and parameter to UserUnbanRequest
- Add FutureChannelBan class for query response
- Add UserQueryFutureChannelBansRequest and UserQueryFutureChannelBansResponse
- Add queryFutureChannelBans factory method and service endpoint

* fix: apply spotless formatting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add targetUserId to UserQueryFutureChannelBansRequestData

Add target_user_id parameter to allow filtering future channel bans
by target user, especially for client-side requests.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* test: add QueryFutureChannelBans test with target_user_id filter

Test the new targetUserId parameter for filtering future channel bans.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fix lint

* Fix tests

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Aditya Alif Nugraha <aditya.nugraha@getstream.io>

Author: 3 people

src/main/java/io/getstream/chat/java/models/User.java

@@ -15,6 +15,7 @@
 import io.getstream.chat.java.models.User.UserMuteRequestData.UserMuteRequest;
 import io.getstream.chat.java.models.User.UserPartialUpdateRequestData.UserPartialUpdateRequest;
 import io.getstream.chat.java.models.User.UserQueryBannedRequestData.UserQueryBannedRequest;
+import io.getstream.chat.java.models.User.UserQueryFutureChannelBansRequestData.UserQueryFutureChannelBansRequest;
 import io.getstream.chat.java.models.User.UserReactivateRequestData.UserReactivateRequest;
 import io.getstream.chat.java.models.User.UserUnmuteRequestData.UserUnmuteRequest;
 import io.getstream.chat.java.models.User.UserUpsertRequestData.UserUpsertRequest;
@@ -214,6 +215,34 @@ public static class Ban {
     private Date createdAt;
   }
 
+  @Data
+  @NoArgsConstructor
+  public static class FutureChannelBan {
+    @Nullable
+    @JsonProperty("user")
+    private User user;
+
+    @Nullable
+    @JsonProperty("banned_by")
+    private User bannedBy;
+
+    @Nullable
+    @JsonProperty("expires")
+    private Date expires;
+
+    @Nullable
+    @JsonProperty("reason")
+    private String reason;
+
+    @Nullable
+    @JsonProperty("shadow")
+    private Boolean shadow;
+
+    @NotNull
+    @JsonProperty("created_at")
+    private Date createdAt;
+  }
+
   @Data
   @NoArgsConstructor
   public static class OwnUser {
@@ -799,6 +828,14 @@ public static class UserBanRequestData {
     @JsonProperty("user")
     private UserRequestObject user;
 
+    @Nullable
+    @JsonProperty("ban_from_future_channels")
+    private Boolean banFromFutureChannels;
+
+    @Nullable
+    @JsonProperty("channel_cid")
+    private String channelCid;
+
     public static class UserBanRequest extends StreamRequest<StreamResponseObject> {
       @Override
       protected Call<StreamResponseObject> generateCall(Client client) {
@@ -1078,6 +1115,10 @@ public static class UserUnbanRequest extends StreamRequest<StreamResponseObject>
 
     @Nullable private Boolean shadow;
 
+    @Nullable private Boolean removeFutureChannelsBan;
+
+    @Nullable private String createdBy;
+
     @NotNull
     public UserUnbanRequest type(@NotNull String type) {
       this.type = type;
@@ -1096,9 +1137,23 @@ public UserUnbanRequest shadow(@NotNull Boolean shadow) {
       return this;
     }
 
+    @NotNull
+    public UserUnbanRequest removeFutureChannelsBan(@NotNull Boolean removeFutureChannelsBan) {
+      this.removeFutureChannelsBan = removeFutureChannelsBan;
+      return this;
+    }
+
+    @NotNull
+    public UserUnbanRequest createdBy(@NotNull String createdBy) {
+      this.createdBy = createdBy;
+      return this;
+    }
+
     @Override
     protected Call<StreamResponseObject> generateCall(Client client) {
-      return client.create(UserService.class).unban(targetUserId, type, id, shadow);
+      return client
+          .create(UserService.class)
+          .unban(targetUserId, type, id, shadow, removeFutureChannelsBan, createdBy);
     }
   }
 
@@ -1171,6 +1226,51 @@ public static class UserQueryBannedResponse extends StreamResponseObject {
     private List<Ban> bans;
   }
 
+  @Builder(
+      builderClassName = "UserQueryFutureChannelBansRequest",
+      builderMethodName = "",
+      buildMethodName = "internalBuild")
+  @Getter
+  @EqualsAndHashCode
+  public static class UserQueryFutureChannelBansRequestData {
+    @Nullable
+    @JsonProperty("user_id")
+    private String userId;
+
+    @Nullable
+    @JsonProperty("target_user_id")
+    private String targetUserId;
+
+    @Nullable
+    @JsonProperty("exclude_expired_bans")
+    private Boolean excludeExpiredBans;
+
+    @Nullable
+    @JsonProperty("limit")
+    private Integer limit;
+
+    @Nullable
+    @JsonProperty("offset")
+    private Integer offset;
+
+    public static class UserQueryFutureChannelBansRequest
+        extends StreamRequest<UserQueryFutureChannelBansResponse> {
+      @Override
+      protected Call<UserQueryFutureChannelBansResponse> generateCall(Client client) {
+        return client.create(UserService.class).queryFutureChannelBans(this.internalBuild());
+      }
+    }
+  }
+
+  @Data
+  @NoArgsConstructor
+  @EqualsAndHashCode(callSuper = true)
+  public static class UserQueryFutureChannelBansResponse extends StreamResponseObject {
+    @NotNull
+    @JsonProperty("bans")
+    private List<FutureChannelBan> bans;
+  }
+
   @Data
   @NoArgsConstructor
   @EqualsAndHashCode(callSuper = true)
@@ -1305,6 +1405,16 @@ public static UserQueryBannedRequest queryBanned() {
     return new UserQueryBannedRequest();
   }
 
+  /**
+   * Creates a query future channel bans request
+   *
+   * @return the created request
+   */
+  @NotNull
+  public static UserQueryFutureChannelBansRequest queryFutureChannelBans() {
+    return new UserQueryFutureChannelBansRequest();
+  }
+
   /**
    * Creates a deactivate request
    *

src/main/java/io/getstream/chat/java/services/UserService.java

@@ -65,5 +65,11 @@ Call<StreamResponseObject> unban(
       @NotNull @Query("target_user_id") String targetUserId,
       @Nullable @Query("type") String channelType,
       @Nullable @Query("id") String channelId,
-      @Nullable @Query("shadow") Boolean shadow);
+      @Nullable @Query("shadow") Boolean shadow,
+      @Nullable @Query("remove_future_channels_ban") Boolean removeFutureChannelsBan,
+      @Nullable @Query("created_by") String createdBy);
+
+  @GET("query_future_channel_bans")
+  Call<UserQueryFutureChannelBansResponse> queryFutureChannelBans(
+      @NotNull @ToJson @Query("payload") UserQueryFutureChannelBansRequestData requestData);
 }

src/test/java/io/getstream/chat/java/UserTest.java

@@ -506,4 +506,72 @@ void whenGeneratingUserToken_thenNoException() {
 
     Assertions.assertEquals(197, token.length());
   }
+
+  @DisplayName("Can query future channel bans with target_user_id filter")
+  @Test
+  void whenQueryingFutureChannelBansWithTargetUserId_thenFiltersCorrectly() {
+    String creatorId = RandomStringUtils.randomAlphabetic(10);
+    String targetId1 = RandomStringUtils.randomAlphabetic(10);
+    String targetId2 = RandomStringUtils.randomAlphabetic(10);
+
+    // Create users
+    UserUpsertRequest usersUpsertRequest = User.upsert();
+    usersUpsertRequest.user(UserRequestObject.builder().id(creatorId).name("Creator").build());
+    usersUpsertRequest.user(UserRequestObject.builder().id(targetId1).name("Target 1").build());
+    usersUpsertRequest.user(UserRequestObject.builder().id(targetId2).name("Target 2").build());
+    Assertions.assertDoesNotThrow(() -> usersUpsertRequest.request());
+
+    // Use the test channel's CID for banning from future channels
+    String channelCid = testChannel.getType() + ":" + testChannel.getId();
+
+    // Ban both targets from future channels created by creator
+    Assertions.assertDoesNotThrow(
+        () ->
+            User.ban()
+                .userId(creatorId)
+                .targetUserId(targetId1)
+                .channelCid(channelCid)
+                .banFromFutureChannels(true)
+                .reason("test ban 1")
+                .request());
+
+    Assertions.assertDoesNotThrow(
+        () ->
+            User.ban()
+                .userId(creatorId)
+                .targetUserId(targetId2)
+                .channelCid(channelCid)
+                .banFromFutureChannels(true)
+                .reason("test ban 2")
+                .request());
+
+    // Query with target_user_id filter - should only return the specific target
+    var response =
+        Assertions.assertDoesNotThrow(
+            () ->
+                User.queryFutureChannelBans().userId(creatorId).targetUserId(targetId1).request());
+    Assertions.assertEquals(1, response.getBans().size());
+    // For future channel bans, banned_by contains the creator (userId)
+    Assertions.assertEquals(creatorId, response.getBans().get(0).getBannedBy().getId());
+
+    // Query for the other target
+    response =
+        Assertions.assertDoesNotThrow(
+            () ->
+                User.queryFutureChannelBans().userId(creatorId).targetUserId(targetId2).request());
+    Assertions.assertEquals(1, response.getBans().size());
+    Assertions.assertEquals(creatorId, response.getBans().get(0).getBannedBy().getId());
+
+    // Query all future channel bans by creator (without target filter)
+    response =
+        Assertions.assertDoesNotThrow(
+            () -> User.queryFutureChannelBans().userId(creatorId).request());
+    Assertions.assertTrue(response.getBans().size() >= 2);
+
+    // Cleanup - unban both users (createdBy is required when removing future channel bans)
+    Assertions.assertDoesNotThrow(
+        () -> User.unban(targetId1).removeFutureChannelsBan(true).createdBy(creatorId).request());
+    Assertions.assertDoesNotThrow(
+        () -> User.unban(targetId2).removeFutureChannelsBan(true).createdBy(creatorId).request());
+  }
 }