feat(api): implement KookChannel updator and extend channel properties

ForteScarlet · ForteScarlet · commit 49dfaa95a305 · 2025-09-12T18:03:40.000+08:00
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -35,32 +35,19 @@ simbot-common-suspend = { group = "love.forte.simbot.common", name = "simbot-com
 simbot-common-annotations = { group = "love.forte.simbot.common", name = "simbot-common-annotations", version.ref = "simbot" }
 simbot-common-loop = { group = "love.forte.simbot.common", name = "simbot-common-stage-loop", version.ref = "simbot" }
 simbot-gradle = { group = "love.forte.simbot.gradle", name = "simbot-gradle-suspendtransforms", version.ref = "simbot" }
+simbot-processor-classBuilder = { module = "love.forte.simbot.processor:simbot-processor-class-builder", version.ref = "simbot" }
 
 # jetbrains-annotation
 jetbrains-annotations = "org.jetbrains:annotations:26.0.2"
 
 # kotlinx-coroutines
 kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-core-jvm = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core-jvm", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-core-js = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core-js", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-jdk8 = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-jdk8", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-reactive = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-reactive", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-reactor = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-reactor", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-rx2 = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-rx2", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-rx3 = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-rx3", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-guava = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-guava", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-slf4j = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-slf4j", version.ref = "kotlinx-coroutines" }
-kotlinx-coroutines-play-services = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-play-services", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-debug = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-debug", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "kotlinx-coroutines" }
 
 # kotlinx-serialization
 kotlinx-serialization-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-core", version.ref = "kotlinx-serialization" }
 kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
-kotlinx-serialization-hocon = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-hocon", version.ref = "kotlinx-serialization" }
-kotlinx-serialization-protobuf = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-protobuf", version.ref = "kotlinx-serialization" }
-kotlinx-serialization-cbor = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-cbor", version.ref = "kotlinx-serialization" }
-kotlinx-serialization-properties = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-properties", version.ref = "kotlinx-serialization" }
 
 # ktor
 ## serialization
diff --git a/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/GetChannelListApi.kt b/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/GetChannelListApi.kt
@@ -123,20 +123,57 @@ public data class ChannelInfo @ApiResultType constructor(
      */
     @SerialName("limit_amount")
     public val limitAmount: Int,
+
+    /**
+     * @since 4.3.0
+     */
+    @SerialName("guild_id")
+    public val guildId: String = "",
+
+    /**
+     * 主题
+     * @since 4.3.0
+     */
+    public val topic: String = "",
+
+    /**
+     * 慢速模式。单位为秒。
+     * @since 4.3.0
+     */
+    @SerialName("slow_mode")
+    public val slowMode: Int = 0,
+
+    /**
+     * @since 4.3.0
+     */
+    @SerialName("permission_overwrites")
+    public val permissionOverwrites: List<PermissionOverwrite> = emptyList(),
+
+    /**
+     * @since 4.3.0
+     */
+    @SerialName("permission_sync")
+    public val permissionSync: Int = 0,
+
+    /**
+     * @since 4.3.0
+     */
+    @SerialName("has_password")
+    public val hasPassword: Boolean = false,
 )
 
 /**
  * 将 [ChannelInfo] 转化为 [Channel] 类型，
  * 并可选的提供一些缺失字段的默认值。
  */
 public fun ChannelInfo.toChannel(
-    guildId: String,
-    topic: String = "",
-    slowMode: Int = 0,
-    permissionOverwrites: List<PermissionOverwrite> = emptyList(),
+    guildId: String = this.guildId,
+    topic: String = this.topic,
+    slowMode: Int = this.slowMode,
+    permissionOverwrites: List<PermissionOverwrite> = this.permissionOverwrites,
     permissionUsers: List<PermissionUser> = emptyList(),
-    permissionSync: Int = 0,
-    hasPassword: Boolean = false,
+    permissionSync: Int = this.permissionSync,
+    hasPassword: Boolean = this.hasPassword,
 ): Channel = ChannelInfoChannel(
     this,
     guildId = guildId,
diff --git a/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/GetChannelViewApi.kt b/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/GetChannelViewApi.kt
@@ -21,8 +21,13 @@ import io.ktor.http.*
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import love.forte.simbot.kook.InternalKookApi
 import love.forte.simbot.kook.api.ApiResultType
 import love.forte.simbot.kook.api.KookGetApi
+import love.forte.simbot.kook.objects.Channel
+import love.forte.simbot.kook.objects.PermissionOverwrite
+import love.forte.simbot.kook.objects.PermissionUser
+import love.forte.simbot.kook.util.BooleanToIntSerializer
 import love.forte.simbot.kook.util.parameters
 import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
@@ -110,20 +115,18 @@ public data class ChannelView @ApiResultType constructor(
 
     /** 是否为分组类型 */
     @SerialName("is_category")
-    public val isCategory: Boolean = type == 0,
+    @Serializable(BooleanToIntSerializer::class)
+    public val isCategory: Boolean = false,
 
     /** 语音服务器地址，HOST:PORT的格式 */
     @SerialName("server_url")
     val serverUrl: String,
 
-    // maybe miss
-
-//    /**
-//     * 针对角色的频道权限覆盖
-//     */
-//    @SerialName("permission_overwrites")
-//    public val permissionOverwrites: List<ChannelPermissionOverwrites> = emptyList(),
-// TODO permissionOverwrites
+    /**
+     * 针对角色的频道权限覆盖
+     */
+    @SerialName("permission_overwrites")
+    public val permissionOverwrites: List<PermissionOverwrite> = emptyList(),
 
     /**
      * 针对用户的频道权限覆盖
@@ -145,3 +148,72 @@ public data class ChannelView @ApiResultType constructor(
      */
     public val children: List<String>? = null
 )
+
+/**
+ * 将 [ChannelView] 转化为 [Channel] 类型，
+ * 并可选的提供一些缺失字段的默认值。
+ *
+ * @since 4.3.0
+ */
+@InternalKookApi
+public fun ChannelView.toChannel(
+    permissionUsers: List<PermissionUser> = emptyList(),
+): Channel = ChannelViewChannel(
+    this,
+    permissionUsers = permissionUsers,
+)
+
+private class ChannelViewChannel(
+    private val channelView: ChannelView,
+    override val permissionUsers: List<PermissionUser>,
+) : Channel {
+    override val id: String
+        get() = channelView.id
+    override val name: String
+        get() = channelView.name
+    override val userId: String
+        get() = channelView.userId
+    override val guildId: String
+        get() = channelView.guildId
+    override val topic: String
+        get() = channelView.topic
+    override val isCategory: Boolean
+        get() = channelView.isCategory
+    override val parentId: String
+        get() = channelView.parentId
+    override val level: Int
+        get() = channelView.level
+    override val slowMode: Int
+        get() = channelView.slowMode
+    override val type: Int
+        get() = channelView.type
+    override val permissionSync: Int
+        get() = channelView.permissionSync
+    override val hasPassword: Boolean
+        get() = channelView.hasPassword
+    override val permissionOverwrites: List<PermissionOverwrite>
+        get() = channelView.permissionOverwrites
+
+    override fun toString(): String {
+        return "ChannelViewChannel(channelView=$channelView, permissionOverwrites=$permissionOverwrites, permissionUsers=$permissionUsers)"
+    }
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is ChannelViewChannel) return false
+
+        if (channelView != other.channelView) return false
+        if (permissionOverwrites != other.permissionOverwrites) return false
+        if (permissionUsers != other.permissionUsers) return false
+
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = channelView.hashCode()
+        result = 31 * result + permissionOverwrites.hashCode()
+        result = 31 * result + permissionUsers.hashCode()
+        return result
+    }
+}
+
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookChannel.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookChannel.kt
@@ -24,8 +24,11 @@ import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.StringID.Companion.ID
 import love.forte.simbot.component.kook.bot.KookBot
 import love.forte.simbot.definition.Channel
+import love.forte.simbot.kook.api.channel.UpdateChannelApi
 import love.forte.simbot.suspendrunner.ST
 import kotlin.coroutines.CoroutineContext
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.seconds
 import love.forte.simbot.kook.objects.Channel as KChannel
 
 
@@ -67,6 +70,63 @@ public interface KookChannel : Channel, DeleteSupport {
     override val name: String
         get() = source.name
 
+    /**
+     * 频道创建者id
+     * @since 4.3.0
+     */
+    public val userId: ID
+        get() = source.userId.ID
+
+    /**
+     * 频道所属服务器id
+     * @since 4.3.0
+     */
+    public val guildId: ID
+        get() = source.guildId.ID
+
+    /**
+     * 频道简介
+     * @since 4.3.0
+     */
+    public val topic: String
+        get() = source.topic
+
+    /**
+     * 上级分组的id
+     * @since 4.3.0
+     */
+    public val parentId: ID
+        get() = source.parentId.ID
+
+    /**
+     * 频道排序level
+     * @since 4.3.0
+     */
+    public val level: Int
+        get() = source.level
+
+    /**
+     * 慢速模式下限制发言的最短时间间隔, 单位为秒(s)
+     * @since 4.3.0
+     * @see slowModeDuration
+     */
+    public val slowMode: Int
+        get() = source.slowMode
+
+    /**
+     * 权限设置是否与分组同步, 1 or 0
+     * @since 4.3.0
+     */
+    public val permissionSync: Int
+        get() = source.permissionSync
+
+    /**
+     * 是否有密码
+     * @since 4.3.0
+     */
+    public val hasPassword: Boolean
+        get() = source.hasPassword
+
     /**
      * 删除此频道。
      *
@@ -87,4 +147,29 @@ public interface KookChannel : Channel, DeleteSupport {
      */
     @ST
     override suspend fun delete(vararg options: DeleteOption)
+
+    /**
+     * 获取一个频道更新器。
+     * 提供需要修改的内容，然后使用 [KookChannelUpdator.execute] 更新频道数据。
+     *
+     * @since 4.3.0
+     */
+    public fun updator(): KookChannelUpdator
 }
+
+/**
+ * 获取频道的慢速模式的持续时间。
+ * @since 4.3.0
+ */
+public val KookChannel.slowModeDuration: Duration
+    get() = when (slowMode) {
+        0 -> Duration.ZERO
+        else -> slowMode.seconds
+    }
+
+/**
+ * 使用 DSL 直接配置 [KookChannelUpdator.builder] 并更新频道信息。
+ * @since 4.3.0
+ */
+public suspend inline fun KookChannel.update(block: UpdateChannelApi.Builder.() -> Unit): KookChannel =
+    updator().apply { builder.block() }.execute()
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookChannelUpdator.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookChannelUpdator.kt
@@ -0,0 +1,57 @@
+/*
+ *     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
+
+import love.forte.simbot.kook.api.ApiResponseException
+import love.forte.simbot.kook.api.channel.UpdateChannelApi
+import love.forte.simbot.suspendrunner.ST
+
+/**
+ * [KookChannel] 的更新器。
+ * @since 4.3.0
+ */
+public interface KookChannelUpdator {
+    public val channel: KookChannel
+
+    /**
+     * 用于构建 [UpdateChannelApi] 的构建器。在 [execute] 中构建并执行。
+     */
+    public var builder: UpdateChannelApi.Builder
+
+    /**
+     * 使用当前的 [builder] 在DSL中配置更新信息。
+     */
+    public fun applyBuilder(block: UpdateChannelApi.Builder.() -> UpdateChannelApi.Builder): KookChannelUpdator =
+        apply {
+            builder = builder.block()
+        }
+
+    /**
+     * 根据当前最终的 [builder] 信息，提供给 [UpdateChannelApi] 并执行更新。
+     *
+     * @see UpdateChannelApi
+     *
+     * @throws ApiResponseException 请求结果的状态码不是 200..300 之间
+     * @throws love.forte.simbot.kook.api.ApiResultException 请求结果的 `code` 校验失败
+     */
+    @ST
+    public suspend fun execute(): KookChannel
+}
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/AbstractKookChatCapableChannelImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/AbstractKookChatCapableChannelImpl.kt
@@ -24,6 +24,7 @@ import love.forte.simbot.ability.DeleteOption
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.kook.KookCategory
+import love.forte.simbot.component.kook.KookChannelUpdator
 import love.forte.simbot.component.kook.KookChatCapableChannel
 import love.forte.simbot.component.kook.bot.internal.KookBotImpl
 import love.forte.simbot.component.kook.message.KookChannelMessageDetailsContent
@@ -68,6 +69,8 @@ internal abstract class AbstractKookChatCapableChannelImpl(
     override suspend fun delete(vararg options: DeleteOption) {
         bot.deleteChannel(source.id, options)
     }
+
+    override fun updator(): KookChannelUpdator = KookChannelUpdatorImpl(this, bot)
 }
 
 internal suspend fun KookChatCapableChannel.send(
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookCategoryChannelImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookCategoryChannelImpl.kt
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookChannelUpdatorImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookChannelUpdatorImpl.kt
