支持频道服务器黑名单相关上层API

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"
         ),
     )
 

buildSrc/src/main/kotlin/P.kt

@@ -35,7 +35,7 @@ object P : ProjectDetail() {
         get() = HOMEPAGE
 
     const val VERSION = "4.3.0"
-    const val NEXT_VERSION = "4.3.1"
+    const val NEXT_VERSION = "4.4.0"
 
     override val snapshotVersion = "$NEXT_VERSION-SNAPSHOT"
     override val version = if (isSnapshot()) snapshotVersion else VERSION

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/api/simbot-component-kook-core.api

@@ -318,6 +318,9 @@ public abstract interface class love/forte/simbot/component/kook/KookVoiceMember
 	public fun moveReserve (Llove/forte/simbot/common/id/ID;)Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
 }
 
+public abstract interface annotation class love/forte/simbot/component/kook/blacklist/ExperimentalBlacklistApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface class love/forte/simbot/component/kook/bot/KookBot : kotlinx/coroutines/CoroutineScope, love/forte/simbot/bot/Bot {
 	public fun cancel (Ljava/lang/Throwable;)V
 	public fun getAvatar ()Ljava/lang/String;

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

@@ -0,0 +1,73 @@
+/*
+ *     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
+
+import love.forte.simbot.ability.DeleteOption
+import love.forte.simbot.ability.DeleteSupport
+import love.forte.simbot.ability.StandardDeleteOption
+import love.forte.simbot.common.id.ID
+import love.forte.simbot.common.time.Timestamp
+import love.forte.simbot.kook.objects.User
+import love.forte.simbot.suspendrunner.ST
+
+/**
+ * KOOK 服务器黑名单列表中的一个元素。
+ *
+ * @since 4.4.0
+ *
+ * @author ForteScarlet
+ */
+@ExperimentalBlacklistApi
+public interface KookBlacklistItem : DeleteSupport {
+    /**
+     * 用户 ID
+     */
+    public val userId: ID
+
+    /**
+     * 服务器 ID
+     */
+    public val guildId: ID
+
+    /**
+     * 加入黑名单的时间
+     */
+    public val createdTime: Timestamp
+
+    /**
+     * 加入黑名单的原因
+     */
+    public val remark: String
+
+    /**
+     * 用户信息。
+     */
+    public val userInfo: User
+
+    /**
+     * 将此人移出黑名单列表。
+     *
+     * @throws RuntimeException 如果在请求API过程中出现任何非预期异常，
+     * 并且没有提供 [StandardDeleteOption.IGNORE_ON_FAILURE]
+     */
+    @ST
+    override suspend fun delete(vararg options: DeleteOption)
+}

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

@@ -0,0 +1,101 @@
+/*
+ *     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
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.toList
+import love.forte.simbot.ability.DeleteOption
+import love.forte.simbot.ability.StandardDeleteOption
+import love.forte.simbot.common.id.ID
+import love.forte.simbot.kook.api.ListData
+import love.forte.simbot.kook.api.blacklist.CreateBlacklistApi
+import love.forte.simbot.suspendrunner.ST
+
+/**
+ * KOOK 服务器黑名单相关内容的操作器。
+ *
+ * @since 4.4.0
+ *
+ * @author ForteScarlet
+ */
+@ExperimentalBlacklistApi
+public interface KookGuildBlacklistOperator {
+    /**
+     * 服务器ID
+     */
+    public val guildId: ID
+
+    /**
+     * 获取黑名单的分页列表。
+     *
+     * @param page 页码
+     * @param size 每页大小
+     * @return 分页列表
+     */
+    @ST
+    public suspend fun list(page: Int?, size: Int?): ListData<KookBlacklistItem>
+
+    /**
+     * 获取全量列表数据。
+     */
+    @ST
+    public suspend fun all(): List<KookBlacklistItem> = flow().toList()
+
+    /**
+     * 获取黑名单列表元素的 Flow。
+     *
+     * @param batchSize 每批次大小
+     */
+    public fun flow(batchSize: Int? = null): Flow<KookBlacklistItem>
+
+    /**
+     * 添加一个目标到黑名单。
+     *
+     * @param guildId 服务器id
+     * @param targetId 目标用户id
+     * @param remark 加入黑名单的原因
+     * @param delMsgDays 删除最近几天的消息，最大 7 天, 默认 0
+     * @see CreateBlacklistApi
+     */
+    @ST
+    public suspend fun add(targetId: ID, remark: String?, delMsgDays: Int?)
+
+    /**
+     * 添加一个目标到黑名单。
+     *
+     * @param guildId 服务器id
+     * @param targetId 目标用户id
+     * @see CreateBlacklistApi
+     */
+    @ST
+    public suspend fun add(targetId: ID) {
+        add(targetId, null, null)
+    }
+
+    /**
+     * 删除指定黑名单内的目标。
+     *
+     * @throws RuntimeException 如果在请求API过程中出现任何非预期异常，
+     * 并且没有提供 [StandardDeleteOption.IGNORE_ON_FAILURE]
+     */
+    @ST
+    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

@@ -0,0 +1,60 @@
+/*
+ *     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.internal
+
+import love.forte.simbot.ability.DeleteOption
+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
+
+/**
+ *
+ * @author ForteScarlet
+ */
+internal class KookBlacklistItemImpl(
+    private val source: BlacklistItem,
+    override val guildId: ID,
+    private val operator: KookGuildBlacklistOperator
+) : KookBlacklistItem {
+    override val userId: ID
+        get() = source.userId.ID
+    override val remark: String
+        get() = source.remark
+    override val userInfo: User
+        get() = source.user
+
+    override val createdTime: Timestamp = Timestamp.ofMilliseconds(source.createdTime)
+
+    override suspend fun delete(vararg options: DeleteOption) {
+        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)