Merge pull request #19 from simple-robot/dev/main

Release: v0.0.7
simple-robot · Jul 20, 2024 · dfe8319 · dfe8319
2 parents ff047ae + 57eb2f0
commit dfe8319
Show file tree

Hide file tree

Showing 9 changed files with 555 additions and 68 deletions.
diff --git a/.changelog/v0.0.7.md b/.changelog/v0.0.7.md
@@ -0,0 +1,7 @@
+> 对应核心版本: [**v4.1.0**](https://github.com/simple-robot/simpler-robot/releases/tag/v4.1.0)
+
+
+我们欢迎并期望着您的的[反馈](https://github.com/simple-robot/simbot-component-telegram/issues)或[协助](https://github.com/simple-robot/simbot-component-telegram/pulls)，
+感谢您的贡献与支持！
+
+也欢迎您为我们献上一颗 `star`，这是对我们最大的鼓励与认可！
diff --git a/README.md b/README.md
@@ -42,10 +42,7 @@ It is also a component library of [Simple Robot v4][simbot4 gh] (simbot), which
 With the capabilities provided by the simbot core library, it can support more advanced encapsulation,
 as well as component collaboration, Spring support, and more.
 
-It can be used as aid as a low-level API/SDK dependency or as a lightweight framework 
-that can be developed quickly with the help of the simbot core library!
-
-Serialization and network requests are based on [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) and [Ktor](https://ktor.io/).
+> Serialization and network requests are based on [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) and [Ktor](https://ktor.io/).
 
 ## Documentation
 
@@ -54,55 +51,259 @@ Serialization and network requests are based on [Kotlin serialization](https://g
 - **API Documentation**: [**The KDoc of Telegram Component**](https://docs.simbot.forte.love/components/telegram) in the [**document guide site**](https://docs.simbot.forte.love). 
 - [**Communities**](https://simbot.forte.love/communities.html): Have fun interacting with us and other developers!
 
-## Modules
-### ⭐ Type module
+## Setup
+
+To use the simbot component library, you first need to add the core implementation of simbot
+(such as the core library (`simbot-core`) or Spring Boot starter (`simbot-core-spring-boot-starter`)),
+and then add the component library dependencies of the Telegram (`simbot-component-telegram-core`).
+
+> [!note]
+> The version of the simbot core implementation library (`SIMBOT_VERSION` below) 
+> goes [here](https://github.com/simple-robot/simpler-robot/releases) for reference;
+>
+> Telegram Component library versions (`VERSION` below) go to the [release](https://github.com/simple-robot/simbot-component-telegram/releases) reference.
+
+**With simbot core**
+
+### Gradle
+
+`build.gradle.kts`
 
-Provides definitions for most types in Telegram and supports serialization based on
-[Kotlin Serialization](https://github.com/Kotlin/kotlinx.serialization).
+```kotlin
+plugins {
+    kotlin("...") version "..."
+}
 
-👉 [Go to the module](simbot-component-telegram-type) to learn more.
+dependencies {
+    implementation("love.forte.simbot:simbot-core:${SIMBOT_VERSION}")
+    implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
+}
+```
+
+### Maven
+
+`pom.xml`
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>love.forte.simbot</groupId>
+        <artifactId>simbot-core-jvm</artifactId>
+        <version>${SIMBOT_VERSION}</version>
+    </dependency>
+    <dependency>
+        <groupId>love.forte.simbot.component</groupId>
+        <artifactId>simbot-component-telegram-core-jvm</artifactId>
+        <version>${VERSION}</version>
+    </dependency>
+</dependencies>
+```
 
-### ⭐ API module
+**With simbot spring boot starter**
 
-Based on [Type module](simbot-component-telegram-type) 
-and [Ktor](https://ktor.io/)'s 
-[KMP][KMP] implementation for [Telegram Bot API][telegram bot doc],
-is a simple, efficient and lightweight API implementation module.
+### Gradle
 
-This module provides very little extra implementation.
-The goal is to preserve the feel of the original API as much as possible without overwrapping it.
+`build.gradle.kts`
 
-👉 [Go to the module](simbot-component-telegram-api) to learn more.
+```kotlin
+plugins {
+    kotlin("jvm") version "..."
+}
 
-### ⭐ Stdlib module
+dependencies {
+    implementation("love.forte.simbot:simbot-core-spring-boot-starter:${SIMBOT_VERSION}")
+    implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
+}
+```
 
-Based on [API module](simbot-component-telegram-api), 
-for the implementation of authentication, subscription events and other related functions in bot.
+### Maven
+
+`pom.xml`
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>love.forte.simbot</groupId>
+        <artifactId>simbot-core-spring-boot-starter</artifactId>
+        <version>${SIMBOT_VERSION}</version>
+    </dependency>
+    <dependency>
+        <groupId>love.forte.simbot.component</groupId>
+        <artifactId>simbot-component-telegram-core-jvm</artifactId>
+        <version>${VERSION}</version>
+    </dependency>
+</dependencies>
+```
 
-The `stdlib` module can be thought of as a lightweight SDK implementation library.
+### Ktor client engine
 
-This module provides an implementation of event-related functionality based on the API module, 
-including the ability to subscribe to events.
+The Telegram component uses Ktor as the HTTP client implementation,
+but does not rely on any specific engine by default.
 
-Again, the goal is to provide as much of the feel of the original API as possible without overwrapping it.
+Therefore, you need to choose and use a Ktor Client engine implementation.
 
-👉 [Go to the module](simbot-component-telegram-stdlib) to learn more.
+You can go to the [Ktor documentation](https://ktor.io/docs/client-engines.html)
+to select a suitable Client Engine for your platform.
 
-### ⭐ Core Component module
+Take the JVM platform as an example:
 
-A component implementation of the [simbot4 core library][simbot4 gh] based on [standard library module](simbot-component-telegram-stdlib).
+<details open><summary>Gradle</summary>
 
-Is a relatively highly encapsulated module that provides most of the capabilities of simbot4, 
-including event listeners, multi-component coordination, Spring Boot starter, and more.
+```kotlin
+runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
+```
 
-👉 [Go to Modules](simbot-component-telegram-core) to learn more.
+</details>
+
+<details ><summary>Maven</summary>
+
+```xml
+<dependency>
+    <groupId>io.ktor</groupId>
+    <artifactId>ktor-client-java-jvm</artifactId>
+    <version>${ktor_version}</version>
+    <scope>runtime</scope>
+</dependency>
+```
+
+</details>
+
+## Examples
+
+**simbot core**
+
+```Kotlin
+suspend fun main() {
+    val app = launchSimpleApplication { 
+        useTelegram() // install Telegram Component
+    }
+
+    // subscribe to events
+    app.listeners {
+        // subscribe to ChatGroupMessageEvent 
+        listen<ChatGroupMessageEvent> { event ->
+            // process event...
+            event.reply("Hello!")
+            event.reply(At(event.authorId) + "Where are you?".toText())
+
+            // Required an result
+            EventResult.empty()
+        }
+
+        // subscribe to ChatGroupMessageEvent
+        process<TelegramPrivateMessageEvent> { event ->
+            // process event...
+            event.content().send("Welcome, " + At(event.member().id))
+
+            // Without result in `process<T>` 
+        }
+    }
+
+    // register bots
+    app.telegramBots {
+        // register a bot via token
+        val bot = register(token = "botaaabbb.123123444") {
+            // Config...
+            // The source stdlib bot config 
+            botConfiguration {
+                apiClientConfigurer {
+                    engine {
+                        // A proxy?
+                        proxy = ProxyBuilder.http("http://127.0.0.1:7790")
+                    }
+                }
+
+                // Enable longPolling?
+                longPolling = LongPolling(
+                    limit = 100,
+                    timeout = 10.minutes.inWholeSeconds.toInt(),
+                    allowedUpdates = setOf(UpdateValues.MESSAGE_NAME),
+                    // Enable retry?
+                    retry = LongPolling.Retry()
+                )
+            }
+        }
+
+        // start the bot
+        bot.start()
+    }
+
+
+    app.join()   
+}
+```
+
+**simbot Spring Boot starter**
+
+```Kotlin
+@SpringBootApplication
+@EnableSimbot // enable
+class App
+
+fun main(args: Array<String>) {
+    runApplication<App>(*args)
+}
+
+@Component
+class MyHandles {
+
+    @Listener // subscribe to ChatGroupMemberIncreaseEvent
+    suspend fun handleMemberIncrease(event: ChatGroupMemberIncreaseEvent) {
+        // ...
+    }
+
+    @Filter("Hello.*")
+    @Listener // subscribe to ChatGroupMessageEvent
+    suspend fun handleGroupMessage(event: ChatGroupMessageEvent) {
+        event.reply("Hello!")
+    }
+}
+```
+The configuration file `*.bot.json`
+
+> Comments are not supported.
+> Remember to clean them up when you use them.
+
+```json5
+{
+    "component": "simbot.telegram",
+    "ticket": {
+        "token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
+    },
+    // config and its properties are optional and default to `null`.
+    "config": {
+        "server": null,
+        "proxy": null,
+        "longPolling": null
+    }
+}
+```
+
+
+```json5
+{
+    "component": "simbot.telegram",
+    "ticket": {
+        "token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
+    },
+    // config and its properties are optional and default to `null`.
+    "config": {
+        "server": null,
+        "proxy": null,
+        // config the `longPolling` to subscribe evnets
+        "longPolling": {
+            "limit": 100
+        }
+    }
+}
+```
 
 ## CONTRIBUTING
 
 See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information! 
 
 We welcome you and look forward to it
-[feed back](https://github.com/simple-robot/simbot-component-telegram/issues)
+[feedback](https://github.com/simple-robot/simbot-component-telegram/issues)
 or
 [pull request](https://github.com/simple-robot/simbot-component-telegram/pulls),
 Thank you for your contribution and support!