Skip to content

Commit

Permalink
Merge pull request #22 from simple-robot/dev/main
Browse files Browse the repository at this point in the history
Release: v0.0.8
  • Loading branch information
ForteScarlet authored Jul 22, 2024
2 parents dfe8319 + 8760109 commit 522ef7f
Show file tree
Hide file tree
Showing 12 changed files with 627 additions and 133 deletions.
7 changes: 7 additions & 0 deletions .changelog/v0.0.8.md
Original file line number Diff line number Diff line change
@@ -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`,这是对我们最大的鼓励与认可!
138 changes: 10 additions & 128 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,144 +33,26 @@ _中文_ | [English](README.md)
>
> [加入社群](https://simbot.forte.love/communities.html)~
这是一个基于 [Kotlin coroutines](https://github.com/Kotlin/kotlinx.coroutines)
[**Telegram Bot**][telegram bot doc] API/SDK
Kotlin 多平台库,异步高效、Java友好
**Telegram组件**
是一个 [Kotlin 多平台](https://kotlinlang.org/docs/multiplatform.html) [**Telegram Bot API**][telegram bot doc] SDK实现库,
也是 Simple Robot 标准API下实现的组件库,异步高效、Java友好

它同样是一个 [Simple Robot v4][simbot4 gh] (下文简称 simbot)
的组件库,是 simbot 的子项目之一。
借助 simbot 核心库提供的能力,它可以支持更多高级功能和封装,比如组件协同、Spring支持等。
> 序列化和网络请求相关分别基于 [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization)
> [Ktor](https://ktor.io/).
它可以作为一个低级别的 API/SDK 辅助依赖库,
也可在 simbot 核心库的支持下用作为一个轻量级的快速开发框架!

序列化和网络请求相关分别基于 [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization)
[Ktor](https://ktor.io/).
> 序列化和网络请求相关分别基于 [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization)
> [Ktor](https://ktor.io/).

## 文档

- **Telegram组件**手册:(待建设)
- 了解simbot: [**Simple Robot 应用手册**](https://simbot.forte.love)
- 手册: [**Simple Robot 应用手册**](https://simbot.forte.love) 及其中的 [**Telegram组件**](https://simbot.forte.love/component-telegram.html) 部分。
- **API文档**: [**文档引导站点**](https://docs.simbot.forte.love) 中 Telegram 的 [**KDoc站点**](https://docs.simbot.forte.love/components/telegram)
- [**社群**](https://simbot.forte.love/communities.html): 与我们和其他开发者愉快地交流!


## 安装

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`

```kotlin
plugins {
kotlin("...") version "..."
}

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>
```

**With simbot spring boot starter**

### Gradle

`build.gradle.kts`

```kotlin
plugins {
kotlin("jvm") version "..."
}

dependencies {
implementation("love.forte.simbot:simbot-core-spring-boot-starter:${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-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>
```

### Ktor client engine

The Telegram component uses Ktor as the HTTP client implementation,
but does not rely on any specific engine by default.

Therefore, you need to choose and use a Ktor Client engine implementation.

You can go to the [Ktor documentation](https://ktor.io/docs/client-engines.html)
to select a suitable Client Engine for your platform.

Take the JVM platform as an example:

<details open><summary>Gradle</summary>

```kotlin
runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
```

</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>
参考手册的 [**Telegram组件**](https://simbot.forte.love/component-telegram.html) 部分。

## Examples

Expand Down
4 changes: 2 additions & 2 deletions buildSrc/src/main/kotlin/P.kt
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ object P {
override val description: String get() = DESCRIPTION
override val homepage: String get() = HOMEPAGE

const val VERSION = "0.0.7"
const val NEXT_VERSION = "0.0.8"
const val VERSION = "0.0.8"
const val NEXT_VERSION = "0.0.9"

override val snapshotVersion = "$NEXT_VERSION-SNAPSHOT"
override val version = if (isSnapshot()) snapshotVersion else VERSION
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
/*
* Copyright (c) 2024. ForteScarlet.
*
* This file is part of simbot-component-telegram.
*
* simbot-component-telegram 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-telegram 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-telegram.
* If not, see <https://www.gnu.org/licenses/>.
*/

package love.forte.simbot.telegram.api.bot.command

import kotlinx.serialization.DeserializationStrategy
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.builtins.serializer
import love.forte.simbot.telegram.api.SimpleBodyTelegramApi
import love.forte.simbot.telegram.api.TelegramApiResult
import love.forte.simbot.telegram.type.BotCommandScope
import kotlin.jvm.JvmOverloads
import kotlin.jvm.JvmStatic


/**
* [deleteMyCommands](https://core.telegram.org/bots/api#deletemycommands)
*
* Use this method to delete the list of the bot's commands for the given scope and user language.
* After deletion, higher level commands will be shown to affected users. Returns True on success.
*
* @author ForteScarlet
*/
public class DeleteMyCommandsApi
private constructor(body: Body) : SimpleBodyTelegramApi<Boolean>() {
public companion object Factory {
private const val NAME = "deleteMyCommands"
private val EMPTY = DeleteMyCommandsApi(Body())

/**
* Create an instance of [DeleteMyCommandsApi].
*
* @param scope A JSON-serialized object, describing scope of users for which the commands are relevant.
* Defaults to BotCommandScopeDefault.
* @param languageCode A two-letter ISO 639-1 language code.
* If empty, commands will be applied to all users from the given scope,
* for whose language there are no dedicated commands
*/
@JvmStatic
@JvmOverloads
public fun create(
scope: BotCommandScope? = null,
languageCode: String? = null,
): DeleteMyCommandsApi {
return if (scope == null && languageCode == null) {
EMPTY
} else {
DeleteMyCommandsApi(
Body(
scope = scope,
languageCode = languageCode
)
)
}
}
}

/**
* Request body for [DeleteMyCommandsApi]
* @property scope A JSON-serialized object, describing scope of users for which the commands are relevant.
* Defaults to BotCommandScopeDefault.
* @property languageCode A two-letter ISO 639-1 language code.
* If empty, commands will be applied to all users from the given scope,
* for whose language there are no dedicated commands
*/
@Serializable
public data class Body(
val scope: BotCommandScope? = null,
@SerialName("language_code")
val languageCode: String? = null,
)

override val name: String
get() = NAME

override val body: Any = body

override val responseDeserializer: DeserializationStrategy<Boolean>
get() = Boolean.serializer()

override val resultDeserializer: DeserializationStrategy<TelegramApiResult<Boolean>>
get() = TelegramApiResult.BooleanSerializer
}

/*
Parameter Type Required Description
*/
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
/*
* Copyright (c) 2024. ForteScarlet.
*
* This file is part of simbot-component-telegram.
*
* simbot-component-telegram 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-telegram 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-telegram.
* If not, see <https://www.gnu.org/licenses/>.
*/

package love.forte.simbot.telegram.api.bot.command

import kotlinx.serialization.DeserializationStrategy
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.builtins.serializer
import love.forte.simbot.telegram.api.SimpleBodyTelegramApi
import love.forte.simbot.telegram.api.TelegramApiResult
import love.forte.simbot.telegram.type.BotCommand
import love.forte.simbot.telegram.type.BotCommandScope
import kotlin.jvm.JvmOverloads
import kotlin.jvm.JvmStatic


/**
* [setMyCommands](https://core.telegram.org/bots/api#setmycommands)
* Use this method to change the list of the bot's commands.
* See this manual for more details about bot commands. Returns True on success.
*
* @author ForteScarlet
*/
public class SetMyCommandsApi
private constructor(body: Body) : SimpleBodyTelegramApi<Boolean>() {
public companion object Factory {
private const val NAME = "setMyCommands"

/**
* Create an instance of [SetMyCommandsApi].
*
* @param commands A JSON-serialized list of bot commands to be set as the list of the bot's commands.
* At most 100 commands can be specified.
* @param scope A JSON-serialized object, describing scope of users for which the commands are relevant.
* Defaults to BotCommandScopeDefault.
* @param languageCode A two-letter ISO 639-1 language code.
* If empty, commands will be applied to all users from the given scope,
* for whose language there are no dedicated commands
*/
@JvmStatic
@JvmOverloads
public fun create(
commands: List<BotCommand>,
scope: BotCommandScope? = null,
languageCode: String? = null,
): SetMyCommandsApi = SetMyCommandsApi(
Body(
commands = commands,
scope = scope,
languageCode = languageCode
)
)
}

/**
* Request body for [SetMyCommandsApi]
* @property commands A JSON-serialized list of bot commands to be set as the list of the bot's commands.
* At most 100 commands can be specified.
* @property scope A JSON-serialized object, describing scope of users for which the commands are relevant.
* Defaults to BotCommandScopeDefault.
* @property languageCode A two-letter ISO 639-1 language code.
* If empty, commands will be applied to all users from the given scope,
* for whose language there are no dedicated commands
*/
@Serializable
public data class Body(
val commands: List<BotCommand> = emptyList(),
val scope: BotCommandScope? = null,
@SerialName("language_code")
val languageCode: String? = null,
)

override val name: String
get() = NAME

override val body: Any = body

override val responseDeserializer: DeserializationStrategy<Boolean>
get() = Boolean.serializer()

override val resultDeserializer: DeserializationStrategy<TelegramApiResult<Boolean>>
get() = TelegramApiResult.BooleanSerializer
}

/*
Parameter Type Required Description
*/
2 changes: 2 additions & 0 deletions simbot-component-telegram-api/supports.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
- [bot](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot)
- [x] [CloseApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/CloseApi.kt)
- [command](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/command)
- [x] [DeleteMyCommandsApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/command/DeleteMyCommandsApi.kt)
- [x] [GetMyCommandsApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/command/GetMyCommandsApi.kt)
- [x] [SetMyCommandsApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/command/SetMyCommandsApi.kt)
- [x] [GetChatMenuButtonApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/GetChatMenuButtonApi.kt)
- [x] [GetMeApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/GetMeApi.kt)
- [x] [GetMyDefaultAdministratorRightsApi](src/commonMain/kotlin/love/forte/simbot/telegram/api/bot/GetMyDefaultAdministratorRightsApi.kt)
Expand Down
Loading

0 comments on commit 522ef7f

Please sign in to comment.