feat(core): 完善黑名单相关的上层 API

Author: ForteScarlet

build.gradle.kts

@@ -79,7 +79,9 @@ apiValidation {
             "love.forte.simbot.annotations.InternalSimbotAPI",
             "love.forte.simbot.kook.ExperimentalKookApi",
             "love.forte.simbot.kook.InternalKookApi",
-            "love.forte.simbot.kook.api.template.ExperimentalTemplateApi"
+            "love.forte.simbot.kook.api.template.ExperimentalTemplateApi",
+            // blacklist APIs
+            "love.forte.simbot.component.kook.blacklist.ExperimentalBlacklistApi"
         ),
     )
 

simbot-component-kook-api/src/jvmMain/java/module-info.java

@@ -16,14 +16,19 @@
     exports love.forte.simbot.kook;
     exports love.forte.simbot.kook.api;
     exports love.forte.simbot.kook.api.asset;
+    exports love.forte.simbot.kook.api.blacklist;
+    exports love.forte.simbot.kook.api.category;
     exports love.forte.simbot.kook.api.channel;
     exports love.forte.simbot.kook.api.guild;
     exports love.forte.simbot.kook.api.invite;
     exports love.forte.simbot.kook.api.member;
     exports love.forte.simbot.kook.api.message;
     exports love.forte.simbot.kook.api.role;
+    exports love.forte.simbot.kook.api.template;
+    exports love.forte.simbot.kook.api.thread;
     exports love.forte.simbot.kook.api.user;
     exports love.forte.simbot.kook.api.userchat;
+    exports love.forte.simbot.kook.api.voice;
     exports love.forte.simbot.kook.event;
     exports love.forte.simbot.kook.messages;
     exports love.forte.simbot.kook.objects;

simbot-component-kook-core/build.gradle.kts

@@ -48,6 +48,7 @@ kotlin {
         optIn.addAll(
             "love.forte.simbot.kook.ExperimentalKookApi",
             "love.forte.simbot.kook.InternalKookApi",
+            "love.forte.simbot.component.kook.blacklist.ExperimentalBlacklistApi"
         )
     }
 
@@ -80,6 +81,7 @@ kotlin {
             implementation(libs.simbot.api)
             implementation(libs.simbot.core)
             implementation(libs.simbot.common.core)
+            implementation(libs.ktor.client.mock)
         }
 
         jvmTest.dependencies {

simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookGuild.kt

@@ -25,6 +25,8 @@ import love.forte.simbot.annotations.ExperimentalSimbotAPI
 import love.forte.simbot.common.collectable.Collectable
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.StringID.Companion.ID
+import love.forte.simbot.component.kook.blacklist.ExperimentalBlacklistApi
+import love.forte.simbot.component.kook.blacklist.KookGuildBlacklistOperator
 import love.forte.simbot.component.kook.role.KookGuildRole
 import love.forte.simbot.component.kook.role.KookGuildRoleCreator
 import love.forte.simbot.component.kook.role.KookRole
@@ -207,4 +209,15 @@ public interface KookGuild : Guild, CoroutineScope, KookRoleOperator {
     @ExperimentalSimbotAPI
     override fun roleCreator(): KookGuildRoleCreator
     //endregion
+
+    // Blacklist
+
+    /**
+     * 获取针对当前频道服务器的黑名单操作器。
+     *
+     * @since 4.4.0
+     * @see KookGuildBlacklistOperator
+     */
+    @ExperimentalBlacklistApi
+    public val blacklist: KookGuildBlacklistOperator
 }

simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/ExperimentalBlacklistApi.kt

@@ -0,0 +1,38 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     This file is part of simbot-component-kook.
+ *
+ *     simbot-component-kook is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     simbot-component-kook is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ *     GNU Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public License
+ *     along with simbot-component-kook,
+ *     If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package love.forte.simbot.component.kook.blacklist
+
+/**
+ * 与频道服务器黑名单列表相关的试验性 API。
+ * 这些 API 仍处于试验性阶段，可能会随时被更改、删除，不保证稳定性。
+ *
+ * @since 4.4.0
+ * @author ForteScarlet
+ */
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
+@MustBeDocumented
+@RequiresOptIn(
+    message = "与频道服务器黑名单列表相关的试验性 API。" +
+            "这些 API 仍处于试验性阶段，可能会随时被更改、删除，不保证稳定性。",
+    level = RequiresOptIn.Level.WARNING
+)
+public annotation class ExperimentalBlacklistApi

simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/KookBlacklistItem.kt

@@ -35,6 +35,7 @@ import love.forte.simbot.suspendrunner.ST
  *
  * @author ForteScarlet
  */
+@ExperimentalBlacklistApi
 public interface KookBlacklistItem : DeleteSupport {
     /**
      * 用户 ID

…/kook/blacklist/KookBlacklistOperator.kt …/blacklist/KookGuildBlacklistOperator.ktsimbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/KookBlacklistOperator.kt renamed to simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/KookGuildBlacklistOperator.kt simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/KookBlacklistOperator.kt renamed to simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/KookGuildBlacklistOperator.kt

@@ -30,13 +30,19 @@ import love.forte.simbot.kook.api.blacklist.CreateBlacklistApi
 import love.forte.simbot.suspendrunner.ST
 
 /**
- * KOOK 黑名单相关内容的操作器。
+ * KOOK 服务器黑名单相关内容的操作器。
  *
  * @since 4.4.0
  *
  * @author ForteScarlet
  */
-public interface KookBlacklistOperator {
+@ExperimentalBlacklistApi
+public interface KookGuildBlacklistOperator {
+    /**
+     * 服务器ID
+     */
+    public val guildId: ID
+
     /**
      * 获取黑名单的分页列表。
      *
@@ -45,21 +51,20 @@ public interface KookBlacklistOperator {
      * @return 分页列表
      */
     @ST
-    public suspend fun list(guildId: ID, page: Int?, size: Int?): ListData<KookBlacklistItem>
+    public suspend fun list(page: Int?, size: Int?): ListData<KookBlacklistItem>
 
     /**
      * 获取全量列表数据。
      */
     @ST
-    public suspend fun all(guildId: ID): List<KookBlacklistItem> =
-        flow(guildId).toList()
+    public suspend fun all(): List<KookBlacklistItem> = flow().toList()
 
     /**
      * 获取黑名单列表元素的 Flow。
      *
      * @param batchSize 每批次大小
      */
-    public fun flow(guildId: ID, batchSize: Int? = null): Flow<KookBlacklistItem>
+    public fun flow(batchSize: Int? = null): Flow<KookBlacklistItem>
 
     /**
      * 添加一个目标到黑名单。
@@ -71,7 +76,7 @@ public interface KookBlacklistOperator {
      * @see CreateBlacklistApi
      */
     @ST
-    public suspend fun add(guildId: ID, targetId: ID, remark: String?, delMsgDays: Int?)
+    public suspend fun add(targetId: ID, remark: String?, delMsgDays: Int?)
 
     /**
      * 添加一个目标到黑名单。
@@ -81,8 +86,8 @@ public interface KookBlacklistOperator {
      * @see CreateBlacklistApi
      */
     @ST
-    public suspend fun add(guildId: ID, targetId: ID) {
-        add(guildId, targetId, null, null)
+    public suspend fun add(targetId: ID) {
+        add(targetId, null, null)
     }
 
     /**
@@ -92,5 +97,5 @@ public interface KookBlacklistOperator {
      * 并且没有提供 [StandardDeleteOption.IGNORE_ON_FAILURE]
      */
     @ST
-    public suspend fun delete(guildId: ID, targetId: ID, vararg options: DeleteOption)
+    public suspend fun delete(targetId: ID, vararg options: DeleteOption)
 }

simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/internal/KookBlacklistItemImpl.kt

@@ -25,6 +25,7 @@ import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.StringID.Companion.ID
 import love.forte.simbot.common.time.Timestamp
 import love.forte.simbot.component.kook.blacklist.KookBlacklistItem
+import love.forte.simbot.component.kook.blacklist.KookGuildBlacklistOperator
 import love.forte.simbot.kook.api.blacklist.BlacklistItem
 import love.forte.simbot.kook.objects.User
 
@@ -34,7 +35,8 @@ import love.forte.simbot.kook.objects.User
  */
 internal class KookBlacklistItemImpl(
     private val source: BlacklistItem,
-    override val guildId: ID
+    override val guildId: ID,
+    private val operator: KookGuildBlacklistOperator
 ) : KookBlacklistItem {
     override val userId: ID
         get() = source.userId.ID
@@ -46,6 +48,13 @@ internal class KookBlacklistItemImpl(
     override val createdTime: Timestamp = Timestamp.ofMilliseconds(source.createdTime)
 
     override suspend fun delete(vararg options: DeleteOption) {
-        TODO("Not yet implemented")
+        operator.delete(targetId = userId, options = options)
     }
-}
+
+    override fun toString(): String {
+        return "KookBlacklistItemImpl(source=$source, guildId=$guildId, userId=$userId)"
+    }
+}
+
+internal fun BlacklistItem.toKookBlacklistItem(guildId: ID, operator: KookGuildBlacklistOperator): KookBlacklistItem =
+    KookBlacklistItemImpl(this, guildId, operator)

…st/internal/KookBlacklistOperatorImpl.kt …ternal/KookGuildBlacklistOperatorImpl.ktsimbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/internal/KookBlacklistOperatorImpl.kt renamed to simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/internal/KookGuildBlacklistOperatorImpl.kt simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/internal/KookBlacklistOperatorImpl.kt renamed to simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/blacklist/internal/KookGuildBlacklistOperatorImpl.kt

@@ -26,52 +26,63 @@ import kotlinx.coroutines.flow.asFlow
 import kotlinx.coroutines.flow.flatMapConcat
 import kotlinx.coroutines.flow.map
 import love.forte.simbot.ability.DeleteOption
+import love.forte.simbot.ability.StandardDeleteOption
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.kook.blacklist.KookBlacklistItem
-import love.forte.simbot.component.kook.blacklist.KookBlacklistOperator
+import love.forte.simbot.component.kook.blacklist.KookGuildBlacklistOperator
 import love.forte.simbot.component.kook.bot.KookBot
 import love.forte.simbot.component.kook.util.requestData
 import love.forte.simbot.kook.api.ListData
+import love.forte.simbot.kook.api.blacklist.CreateBlacklistApi
+import love.forte.simbot.kook.api.blacklist.DeleteBlacklistApi
 import love.forte.simbot.kook.api.blacklist.GetBlacklistListApi
 import love.forte.simbot.kook.api.blacklist.createFlow
 
 /**
  *
  * @author ForteScarlet
  */
-internal class KookBlacklistOperatorImpl(private val bot: KookBot) : KookBlacklistOperator {
+internal class KookGuildBlacklistOperatorImpl(
+    private val bot: KookBot,
+    override val guildId: ID
+) : KookGuildBlacklistOperator {
     override suspend fun list(
-        guildId: ID,
         page: Int?,
         size: Int?
     ): ListData<KookBlacklistItem> {
-        TODO("Not yet implemented")
+        val api = GetBlacklistListApi.create(guildId = guildId.literal, page = page, pageSize = size)
+        val raw = bot.requestData(api)
+        return ListData(
+            raw.items.map { it.toKookBlacklistItem(guildId, this) },
+            raw.meta,
+            raw.sort
+        )
     }
 
     @OptIn(ExperimentalCoroutinesApi::class)
-    override fun flow(guildId: ID, batchSize: Int?): Flow<KookBlacklistItem> {
+    override fun flow(batchSize: Int?): Flow<KookBlacklistItem> {
         return GetBlacklistListApi.createFlow { page ->
             val api = GetBlacklistListApi.create(guildId = guildId.literal, page = page, pageSize = batchSize)
             bot.requestData(api)
         }.flatMapConcat { it.items.asFlow() }
-            .map { TODO("Not yet implemented") }
+            .map { it.toKookBlacklistItem(guildId, this) }
     }
 
-    override suspend fun add(
-        guildId: ID,
-        targetId: ID,
-        remark: String?,
-        delMsgDays: Int?
-    ) {
-        TODO("Not yet implemented")
+    override suspend fun add(targetId: ID, remark: String?, delMsgDays: Int?) {
+        val api = CreateBlacklistApi.create(guildId.literal, targetId.literal, remark, delMsgDays)
+        bot.requestData(api)
     }
 
-    override suspend fun delete(
-        guildId: ID,
-        targetId: ID,
-        vararg options: DeleteOption
-    ) {
-        TODO("Not yet implemented")
+    override suspend fun delete(targetId: ID, vararg options: DeleteOption) {
+        val api = DeleteBlacklistApi.create(guildId.literal, targetId.literal)
+
+        if (options.contains(StandardDeleteOption.IGNORE_ON_FAILURE)) {
+            runCatching { bot.requestData(api) }
+            // Log?
+            return
+        }
+
+        bot.requestData(api)
     }
 }

simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookGuildImpl.kt

@@ -29,6 +29,9 @@ import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.StringID.Companion.ID
 import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.kook.*
+import love.forte.simbot.component.kook.blacklist.ExperimentalBlacklistApi
+import love.forte.simbot.component.kook.blacklist.KookGuildBlacklistOperator
+import love.forte.simbot.component.kook.blacklist.internal.KookGuildBlacklistOperatorImpl
 import love.forte.simbot.component.kook.bot.internal.KookBotImpl
 import love.forte.simbot.component.kook.role.KookGuildRole
 import love.forte.simbot.component.kook.role.KookGuildRoleCreator
@@ -143,6 +146,10 @@ internal class KookGuildImpl(
     @ExperimentalSimbotAPI
     override fun roleCreator(): KookGuildRoleCreator = KookGuildRoleCreatorImpl(bot, this)
 
+    @ExperimentalBlacklistApi
+    override val blacklist: KookGuildBlacklistOperator
+        get() = KookGuildBlacklistOperatorImpl(bot, id)
+
     override fun toString(): String {
         return "KookGuild(id=${source.id}, name=${source.name})"
     }