packages update

2025-09-03 07:09:23 +00:00 · 2021-10-18 15:20:25 +06:00
parent 91212eaa3a
commit e60eb68b67
235 changed files with 681 additions and 109 deletions
--- a/tgbotapi.api/README.md
+++ b/tgbotapi.api/README.md
@@ -0,0 +1,140 @@
+# TelegramBotAPI extensions
+
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.extensions.api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi.extensions.api)
+
+- [TelegramBotAPI extensions](#telegrambotapi-extensions)
+    * [What is it?](#what-is-it)
+    * [Compatibility](#compatibility)
+    * [How to implement library?](#how-to-implement-library)
+        + [Maven](#maven)
+        + [Gradle](#gradle)
+    * [Example of usage and comparison with `TelegramBotAPI`](#example-of-usage-and-comparison-with-telegrambotapi)
+    * [Updates](#updates)
+        + [Alternative way](#alternative-way)
+
+<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
+
+## What is it?
+
+It is wrapper library for [TelegramBotAPI Core](../tgbotapi.core/README.md). Here you can find extensions for
+`RequestsExecutor`, which are more look like Telegram Bot API requests and in the same time have more obvious signatures
+to help understand some restrictions in Telegram system.
+
+## Compatibility
+
+This library always compatible with original `tgbotapi.core` library version
+
+## How to implement library?
+
+Common ways to implement this library are presented here. In some cases it will require additional steps
+like inserting of additional libraries (like `kotlin stdlib`). In the examples will be used variable
+`telegrambotapi-extensions-api.version`, which must be set up by developer. Available versions are presented on
+[bintray](https://bintray.com/insanusmokrassar/TelegramBotAPI/tgbotapi.extensions.api), next version is last published:
+
+[![Download](https://api.bintray.com/packages/insanusmokrassar/TelegramBotAPI/tgbotapi.extensions.api/images/download.svg) ](https://bintray.com/insanusmokrassar/TelegramBotAPI/tgbotapi.extensions.api/_latestVersion)
+
+### Maven
+
+Dependency config presented here:
+
+```xml
+<dependency>
+  <groupId>dev.inmo</groupId>
+  <artifactId>tgbotapi.extensions.api</artifactId>
+  <version>${telegrambotapi-extensions-api.version}</version>
+</dependency>
+```
+
+### Gradle
+
+To use last versions you will need to add one line in repositories block of your `build.gradle`:
+
+`mavenCentral()`
+
+And add next line to your dependencies block:
+
+```groovy
+implementation "dev.inmo:tgbotapi.extensions.api:$telegrambotapi_extensions_api_version"
+```
+
+or for old gradle:
+
+```groovy
+compile "dev.inmo:tgbotapi.extensions.api:$telegrambotapi_extensions_api_version"
+```
+
+## Example of usage and comparison with `TelegramBotAPI`
+
+Here presented review table for comparison of api from original [TelegramBotAPI](../TelegramBotAPI/README.md#Requests)
+and extensions-api library. First of all, this library allow to create bot instance in a new way:
+
+```kotlin
+val bot = telegramBot("IT IS YOUR TOKEN")
+```
+
+There are a lot of signature for this. For example, you can create bot with next code:
+
+```kotlin
+val bot = telegramBot("IT IS YOUR TOKEN") {
+    proxy = ProxyBuilder.socks("127.0.0.1", 1080)
+}
+```
+
+In all examples supposed that you have created bot.
+
+| tgbotapi.core | tgbotapi.extensions.api |
+|---------------------|-------------------------------|
+| bot.execute(GetMe) |    bot.getMe()          |
+| bot.execute(SendTextMessage(someChatId, text)) | bot.sendTextMessage(chat, text) |
+
+## Updates
+
+**Currently, these paragraphs almost outdated due to the fact that extensions for listening of updates and webhooks were
+replaced into `tgbotapi.extensions.utils`. But, most part of information below is correct with small fixes and
+adding of `tgbotapi.extensions.utils` dependency.**
+
+Usually, it is more comfortable to use filter object to get separated types of updates:
+
+```kotlin
+val filter = FlowsUpdatesFilter(100)
+```
+
+In this case you will be able:
+
+* Separate types of incoming updates (even media groups)
+* Simplify launch of getting updates:
+```kotlin
+bot.startGettingOfUpdates(
+    filter,
+    scope = CoroutineScope(Dispatchers.Default)
+)
+```
+* Use `filter` flows to comfortable filter, map and do other operations with the whole
+getting updates process:
+```kotlin
+filter.messageFlow.mapNotNull {
+    it.data as? ContentMessage<*>
+}.onEach {
+    println(it)
+}.launchIn(
+    CoroutineScope(Dispatchers.Default)
+)
+```
+
+### Alternative way
+
+There is an alternative way to get updates. In fact it is almost the same, but could be more useful for some cases:
+
+```kotlin
+val filter = bot.startGettingOfUpdates(
+    scope = CoroutineScope(Dispatchers.Default)
+) { // Here as reveiver will be FlowsUpdatesFilter
+    messageFlow.mapNotNull {
+        it.data as? ContentMessage<*>
+    }.onEach {
+        println(it)
+    }.launchIn(
+        CoroutineScope(Dispatchers.Default)
+    )
+}
+```