Release: v4.3.0

.github/ISSUE_TEMPLATE/advice.yml

@@ -1,5 +1,5 @@
-name: "💡意见建议"
-description: "提出你的好想法"
+name: "💡意见、建议或协助"
+description: "提出你的好想法，或者你打算做的事"
 labels: [ "建议" ]
 assignees: [ "ForteScarlet" ]
 # https://docs.github.com/cn/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
@@ -18,10 +18,21 @@ body:
          请知悉以下内容：
          1. 当意见建议未被完全确认或等待发起者回复的情况下，发起者如果超过一周未作应答，则会视为「无效」并做关闭处理。
          2. 仅接受针对于框架本身的合理建议。被团队认定为不合理的建议将会被拒绝。
-         3. 如果有能力，可以通过 [pr](https://github.com/ForteScarlet/simpler-robot/pulls) 向我们提供代码协助，非常感谢。
 
          <hr />
-
+  - type: dropdown
+    id: will-contribute
+    attributes:
+      label: 是否会提供贡献？
+      description: 如果此条议题是你打算提供代码贡献作为前提，那么标记它，来告诉我们与其他开发者，避免产生重复劳动~
+      options:
+        - 不确定
+        - 是
+        - 否
+      default: 0
+    validations:
+      required: true
+
   - type: textarea
     id: advice
     attributes:

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -21,14 +21,26 @@ body:
          3. 当问题反馈未被完全确认或等待发起者回复的情况下，发起者如果超过一周未作应答，则会视为「无效」并做关闭处理。
 
          <hr />
-
-
+
+  - type: dropdown
+    id: will-contribute
+    attributes:
+      label: 是否会提供贡献？
+      description: 如果此条议题是你打算提供代码贡献作为前提，那么标记它，来告诉我们与其他开发者，以避免产生可能的重复劳动
+      options:
+        - 否
+        - 是
+        - 不确定
+      default: 0
+    validations:
+      required: true
+
   - type: input
     id: version
     attributes:
       label: 版本号
       description: 涉及的具体版本
-      placeholder: "例如: v3.0.0-xx 或 v6.6.6 等"
+      placeholder: "例如: v4.x.x 或 v6.6.6 等"
     validations:
       required: true       
 
@@ -37,7 +49,7 @@ body:
     attributes:
       label: 附加版本
       description: 如果有需要补充的其他版本信息，可以在此补充
-      placeholder: "例如: simbot-component-kook: v3.0.0.0-xx"
+      placeholder: "例如: simbot-component-kook: va.b.c"
 
   - type: dropdown
     id: language
@@ -70,13 +82,12 @@ body:
       description: 请尽可能准确的选择使用的组件
       multiple: true
       options:
-        - KOOK
-        - QQ频道
-        - Kritor
+        - QQ机器人
         - OneBot
-        - Discord
+        - KOOK
         - Telegram
-        - mirai
+        - Discord
+        - Kritor
         - 其他
 
   - type: textarea

.github/ISSUE_TEMPLATE/config.yml

@@ -4,9 +4,6 @@ contact_links:
   - name: 讨论社区
     url: https://github.com/orgs/simple-robot/discussions
     about: 前往讨论区与开发团队或其他人交流、互动
-  - name: v3文档反馈
-    url: https://github.com/simple-robot-library/simbot3-website/issues/new/choose
-    about: 对官网 simbot.forte.love 的反馈
   - name: v4文档反馈
     url: https://github.com/simple-robot-library/simbot4-website/issues/new/choose
-    about: 对官网 simbot4.forte.love 的反馈
+    about: 对官网 simbot.forte.love 的反馈

.github/ISSUE_TEMPLATE/question.yml

@@ -33,7 +33,7 @@ body:
     attributes:
       label: 版本号
       description: 疑问所涉及的版本
-      placeholder: "例如: v3.0.0"
+      placeholder: "例如: v4.0.0"
     validations:
       required: true
 
@@ -56,12 +56,12 @@ body:
       description: 如果没有或无对应选项则在后续描述中补充说明
       multiple: true
       options:
-        - KOOK
-        - QQ频道
-        - Kritor
+        - QQ机器人
         - OneBot
-        - Discord
+        - KOOK
         - Telegram
+        - Discord
+        - Kritor
         - 其他
 
   - type: textarea

CHANGELOG.md

@@ -1,3 +1,21 @@
+# v4.3.0
+
+> Release & Pull Notes: [v4.3.0](https://github.com/simple-robot/simpler-robot/releases/tag/v4.3.0) 
+
+- feat(api): 增加接口 RichMediaMessage 用以描述一个富媒体消息元素 ([`eceb41528..6ec2a1a53`](https://github.com/simple-robot/simpler-robot/compare/eceb41528..7e52e17bc))
+
+    <details><summary><code>eceb41528..6ec2a1a53</code></summary>
+
+    - [`eceb41528`](https://github.com/simple-robot/simpler-robot/commit/eceb41528)
+    - [`fcd2fd670`](https://github.com/simple-robot/simpler-robot/commit/fcd2fd670)
+    - [`c38c80270`](https://github.com/simple-robot/simpler-robot/commit/c38c80270)
+    - [`6ec2a1a53`](https://github.com/simple-robot/simpler-robot/commit/6ec2a1a53)
+
+    </details>
+
+- feat(api): 增加接口 BinaryDataAwareMessage 用以描述能够获取到二进制数据的消息元素 ([`7e52e17bc`](https://github.com/simple-robot/simpler-robot/commit/7e52e17bc))
+- optimize(api): 增加接口 UrlAwareMessage 用以描述能够获取到 URL 信息的消息元素 ([`933095e9d`](https://github.com/simple-robot/simpler-robot/commit/933095e9d))
+
 # v4.2.0
 
 > Release & Pull Notes: [v4.2.0](https://github.com/simple-robot/simpler-robot/releases/tag/v4.2.0) 

buildSrc/src/main/kotlin/P.kt

@@ -44,16 +44,17 @@ fun isSnapshot(): Boolean = _isSnapshot
 /**
  * Project versions.
  */
+@Suppress("MemberVisibilityCanBePrivate")
 sealed class P(override val group: String) : ProjectDetail() {
     /*
     val groupProject = P::class.sealedSubclasses.mapNotNull { it.objectInstance }.associateBy { obj -> obj.group }
             project = groupProject[p.group] ?: error("unknown project group: ${p.group}")
 
      */
     companion object {
-        const val VERSION = "4.2.0"
+        const val VERSION = "4.3.0"
+        const val NEXT_VERSION = "4.3.1"
         const val SNAPSHOT_VERSION = "$VERSION-SNAPSHOT"
-        const val NEXT_VERSION = "4.2.0"
         const val NEXT_SNAPSHOT_VERSION = "$NEXT_VERSION-SNAPSHOT"
 
         const val GROUP = "love.forte.simbot"

gradle/libs.versions.toml

@@ -151,10 +151,10 @@ detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
 # Kover
 # https://www.jetbrains.com/help/qodana/code-coverage.html
 # https://github.com/Kotlin/kotlinx-kover
-kotlinxKover = { id = "org.jetbrains.kotlinx.kover", version = "0.8.1" }
+kotlinxKover = { id = "org.jetbrains.kotlinx.kover", version = "0.8.2" }
 # binary-compatibility-validator
 # https://github.com/Kotlin/binary-compatibility-validator
-kotlinxBinaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.15.0" }
+kotlinxBinaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.15.1" }
 
 [bundles]
 gradle-common = ["gradle-common-core", "gradle-common-multiplatform", "gradle-common-publication"]

simbot-api/api/simbot-api.api

@@ -1830,7 +1830,14 @@ public final class love/forte/simbot/message/AtAll : love/forte/simbot/message/M
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class love/forte/simbot/message/Emoji : love/forte/simbot/message/EmoticonMessage {
+public abstract interface class love/forte/simbot/message/BinaryDataAwareMessage {
+	public abstract synthetic fun binaryData (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun getBinaryData ()[B
+	public fun getBinaryDataAsync ()Ljava/util/concurrent/CompletableFuture;
+	public fun getBinaryDataReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
+}
+
+public final class love/forte/simbot/message/Emoji : love/forte/simbot/message/EmoticonMessage, love/forte/simbot/message/StandardMessage {
 	public static final field Companion Llove/forte/simbot/message/Emoji$Companion;
 	public fun <init> (Llove/forte/simbot/common/id/ID;)V
 	public final fun component1 ()Llove/forte/simbot/common/id/ID;
@@ -1860,7 +1867,7 @@ public final class love/forte/simbot/message/Emoji$Companion {
 public abstract interface class love/forte/simbot/message/EmoticonMessage : love/forte/simbot/message/StandardMessage {
 }
 
-public final class love/forte/simbot/message/Face : love/forte/simbot/message/EmoticonMessage {
+public final class love/forte/simbot/message/Face : love/forte/simbot/message/EmoticonMessage, love/forte/simbot/message/StandardMessage {
 	public static final field Companion Llove/forte/simbot/message/Face$Companion;
 	public fun <init> (Llove/forte/simbot/common/id/ID;)V
 	public final fun component1 ()Llove/forte/simbot/common/id/ID;
@@ -1891,7 +1898,7 @@ public abstract interface class love/forte/simbot/message/IDAwareImage : love/fo
 	public abstract fun getId ()Llove/forte/simbot/common/id/ID;
 }
 
-public abstract interface class love/forte/simbot/message/Image : love/forte/simbot/message/StandardMessage {
+public abstract interface class love/forte/simbot/message/Image : love/forte/simbot/message/RichMediaMessage, love/forte/simbot/message/StandardMessage {
 }
 
 public abstract interface class love/forte/simbot/message/JvmOfflineImageResolver : love/forte/simbot/message/OfflineImageResolver {
@@ -2248,6 +2255,9 @@ public abstract interface class love/forte/simbot/message/RemoteUrlAwareImage :
 	public abstract synthetic fun url (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
+public abstract interface class love/forte/simbot/message/RichMediaMessage : love/forte/simbot/message/StandardMessage {
+}
+
 public final class love/forte/simbot/message/SimpleOfflineResourceImage : love/forte/simbot/message/OfflineResourceImage {
 	public static final field Companion Llove/forte/simbot/message/SimpleOfflineResourceImage$Companion;
 	public fun <init> (Llove/forte/simbot/resource/Resource;)V
@@ -2319,7 +2329,11 @@ public final class love/forte/simbot/message/Text$Companion {
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
 }
 
-public abstract interface class love/forte/simbot/message/UrlAwareImage : love/forte/simbot/message/Image {
+public abstract interface class love/forte/simbot/message/UrlAwareImage : love/forte/simbot/message/Image, love/forte/simbot/message/UrlAwareMessage {
+	public abstract synthetic fun url (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+}
+
+public abstract interface class love/forte/simbot/message/UrlAwareMessage {
 	public fun getUrl ()Ljava/lang/String;
 	public fun getUrlAsync ()Ljava/util/concurrent/CompletableFuture;
 	public fun getUrlReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/AwareMessages.kt

@@ -0,0 +1,86 @@
+/*
+ *     Copyright (c) 2024. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program 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.
+ *
+ *     This program 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
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+@file:JvmName("StandardMessages")
+@file:JvmMultifileClass
+
+package love.forte.simbot.message
+
+import love.forte.simbot.suspendrunner.STP
+import kotlin.jvm.JvmMultifileClass
+import kotlin.jvm.JvmName
+
+
+/**
+ * 表示为一个可以得知 URL 地址的消息元素，
+ * 例如 [UrlAwareImage]。
+ * 应当由某个 [Message.Element] 的子类型实现。
+ *
+ * [UrlAwareMessage] 主要用于那些从服务端返回的消息元素使用，
+ * 而不是本地构建的消息元素。
+ *
+ * @since 4.3.0
+ */
+public interface UrlAwareMessage {
+    /**
+     * 获取到链接字符串。
+     * 如果链接信息包含在响应数据中，则会立即返回，
+     * 否则会挂起并查询链接信息（例如通过网络接口查询）。
+     * 如果需要查询，其内部不会缓存结果，因此每次调用 [url]
+     * 均会产生挂起与查询行为。
+     *
+     * @throws IllegalStateException 如果当前状态无法查询信息，
+     * 比如由于消息元素的序列化导致某些认证信息丢失。
+     * @throws RuntimeException 在获取过程中可能产生的任何异常，
+     * 比如网络请求问题、权限问题等。
+     * JVM中的受检异常应当被包装为非受检异常。具体其他可能的异常请参考具体实现说明。
+     */
+    @STP
+    public suspend fun url(): String
+}
+
+/**
+ * 表示一个可以获取到其二进制数据的消息元素，
+ * 例如某种图片消息或文件消息。
+ * 应当由某个 [Message.Element] 的子类型实现。
+ *
+ * [BinaryDataAwareMessage] 主要用于那些从服务端返回的消息元素使用，
+ * 而不是本地构建的消息元素。
+ *
+ * 注意：如果文件很大，则操作可能会比较耗时。
+ *
+ * @since 4.3.0
+ */
+public interface BinaryDataAwareMessage {
+    /**
+     * 获取到二进制数据。当需要进行网络请求才可得到内容时，会挂起。
+     *
+     * @throws IllegalStateException 如果当前状态无法读取数据，
+     * 比如由于消息元素的序列化导致某些认证信息丢失。
+     * @throws RuntimeException 在获取过程中可能产生的任何异常，
+     * 比如网络请求问题、权限问题等。
+     * JVM中的受检异常应当被包装为非受检异常。具体其他可能的异常请参考具体实现说明。
+     */
+    @STP
+    public suspend fun binaryData(): ByteArray
+}