From 5da60b4ac23e2f1f1389e581cf0f4175df4a4913 Mon Sep 17 00:00:00 2001 From: InsanusMokrassar Date: Mon, 17 Feb 2020 15:25:08 +0600 Subject: [PATCH] update README --- README.md | 250 ++---------------------- TelegramBotAPI-extensions-api/README.md | 75 +++++++ TelegramBotAPI/README.md | 204 +++++++++++++++++++ 3 files changed, 294 insertions(+), 235 deletions(-) create mode 100644 TelegramBotAPI-extensions-api/README.md create mode 100644 TelegramBotAPI/README.md diff --git a/README.md b/README.md index 2293a905ba..c6c2b70bc9 100644 --- a/README.md +++ b/README.md @@ -7,244 +7,24 @@ [![Chat in Telegram](badges/chat.svg)](https://t.me/InMoTelegramBotAPI) - ## What is it? -Library for Object-Oriented and type-safe work with Telegram Bot API. Most part of some specific solves or unuseful +It is a complex of libraries for working with `TelegramBotAPI` in type-safe and strict way as much as it possible. In +the list of this complex currently next projects: + +* [TelegramBotAPI](TelegramBotAPI/README.md) - core of library. In fact it is independent library and can be used alone +without any additional library +* [TelegramBotAPI Extensions](TelegramBotAPI-extensions-api/README.md) - contains extensions (mostly for +`RequestsExecutor`), which allows to use the core library in more pleasant way + +Most part of some specific solves or unuseful moments are describing by official [Telegram Bot API](https://core.telegram.org/bots/api). -## Compatibility +## Ok, where should I start? -This version compatible with [23th of January 2020 update of TelegramBotAPI (version 4.6)](https://core.telegram.org/bots/api#january-23-2020). -There is Telegram Passport API exception of implemented functionality, which was presented in -[August 2018 update of TelegramBotAPI](https://core.telegram.org/bots/api-changelog#august-27-2018) update. It will be implemented -as soon as possible. All APIs that are not included are presented -[wiki](https://github.com/InsanusMokrassar/TelegramBotAPI/wiki/Not-included-API). +Firstly, look at the [TelegramBotAPI](TelegramBotAPI/README.md). Here you can find all information about currently +covered Telegram Bot API and other things. After this you can look at the +[TelegramBotAPI Extensions](TelegramBotAPI-extensions-api/README.md). -## 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.version`, which must be set up by developer. Available versions are presented on -[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI), next version is last published: - -[![Download](https://api.bintray.com/packages/insanusmokrassar/StandardRepository/TelegramBotAPI/images/download.svg) ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion) - -Currently, last versions of library can be available from the Maven repository with errors (for the reason difficult in publishing -of signed artifacts in Bintray). You can: - -* Use earlier version (available version you can find -[here](https://mvnrepository.com/artifact/com.github.insanusmokrassar/TelegramBotAPI)) -* Add `jCenter` repository in build config - -### TelegramBotAPI - -Contains core and most required things, like types, requests and `KtorRequestsExecutor`. - -#### Maven - -Dependency config presented here: - -```xml - - com.github.insanusmokrassar - TelegramBotAPI - ${telegrambotapi.version} - -``` - -#### Gradle - -To use last versions you will need to add one line in repositories block of your `build.gradle`: - -`jcenter()` or `mavenCentral()` - -And add next line to your dependencies block: - -```groovy -implementation "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version" -``` - -or for old gradle: - -```groovy -compile "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version" -``` - -### API extensions - -Contains extensions for `RequestsExecutor` which usually more obvious than original ones in `TelegramBotAPI` and more -useful. - -#### Maven - -Dependency config presented here: - -```xml - - com.github.insanusmokrassar - TelegramBotAPI-extensions-api - ${telegrambotapi.version} - -``` - -#### Gradle - -To use last versions you will need to add one line in repositories block of your `build.gradle`: - -`jcenter()` or `mavenCentral()` - -And add next line to your dependencies block: - -```groovy -implementation "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_version" -``` - -or for old gradle: - -```groovy -compile "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_version" -``` - -## How to work with library? - -For now, this library have no some API god-object. Instead of this, this library has several -important objects: - -* [RequestsExecutor](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/bot/RequestsExecutor.kt) -* [Requests](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests) -* [Types](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types) - -### Types - -Types declare different objects representation. For example, `Chat` for now represented as -interface and has several realisations: - -* `PrivateChat` -* `GroupChat` -* `SupergroupChat` -* `ChannelChat` - -Instead of common garbage with all information as in original [Chat](https://core.telegram.org/bots/api#chat), -here it was separated for more obvious difference between chats types and their possible content. - -The same principle work with a lot of others things in this Telegram bot API. - -### Requests - -Requests usually are very simple objects, but some of them are using their own -build factories. For example, the next code show, how to get information about bot: - -```kotlin -val requestsExecutor: RequestsExecutor = ... -requestsExecutor.execute(GetMe()) -``` - -Or you can use new syntax (available by implementing of project [API extensions](#API-extensions): - -```kotlin -val bot: RequestsExecutor = ... -bot.getMe() -``` - -The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt) -request is -[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt). - -### RequestsExecutor - -It is base object which can be used to execute requests in API. For now by default included Ktor -realisation of `RequestsExecutor`, but it is possible, that in future it will be extracted in separated -project. How to create `RequestsExecutor`: - -```kotlin -val requestsExecutor = KtorRequestsExecutor( - TelegramAPIUrlsKeeper(TOKEN) -) -``` - -Here: - -* `KtorRequestsExecutor` - default realisation with [ktor](https://ktor.io) -* `TelegramAPIUrlsKeeper` - special keeper, which you can save and use for getting files full urls (`resolveFileURL` -extension inside of `PathedFile.kt`) -* `TOKEN` is just a token of bot which was retrieved according to -[instruction](https://core.telegram.org/bots#3-how-do-i-create-a-bot). - -By default, for JVM there is implemented `CIO` client engine, but there is not server engine. Both can be changed like -here: - -```groovy -dependencies { - // ... - implementation "io.ktor:ktor-server-cio:$ktor_version" // for implementing of server engine - implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine - // ... -} -``` - -You can avoid using of `server` dependency in case if you will not use `Webhook`s. In this case, -dependencies list will be simplify: - -```groovy -dependencies { - // ... - implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine - // ... -} -``` - -Here was used `okhttp` realisation of client, but there are several others engines for Ktor. More information -available on ktor.io site for [client](https://ktor.io/clients/http-client/engines.html) and [server](https://ktor.io/quickstart/artifacts.html) -engines. - -## Getting updates - -In this library currently realised two ways to get updates from telegram: - -* Polling - in this case bot will request updates from time to time (you can set up delay between requests) -* Webhook via reverse proxy or something like this - -### Updates filters - -Currently webhook method contains `UpdatesFilter` as necessary argument for getting updates. -`UpdatesFilter` will sort updates and throw their into different callbacks. Currently supporting -separate getting updates for media groups - they are accumulating with debounce in one second -(for being sure that all objects of media group was received). - -Updates polling also support `UpdatesFilter` but it is not required to use it and you can get updates directly -in `UpdateReceiver`, which you will provide to `startGettingOfUpdates` method - -### Webhook set up - -If you wish to use webhook method, you will need: - -* White IP - your IP address or host, which available for calling. [TelegramBotAPI](https://core.telegram.org/bots/api#setwebhook) -recommend to use some unique address for each bot which you are using -* SSL certificate. Usually you can obtain the certificate using your domain provider, [Let'sEncrypt](https://letsencrypt.org/) or [create it](https://core.telegram.org/bots/self-signed) -* Nginx or something like this - -Template for Nginx server config you can find in [this gist](https://gist.github.com/InsanusMokrassar/fcc6e09cebd07e46e8f0fdec234750c4#file-nginxssl-conf). - -For webhook you can provide `File` with public part of certificate, `URL` where bot will be available and inner `PORT` which -will be used to start receiving of updates. Actually, you can skip passing of `File` when you have something like -nginx for proxy forwarding. - -In case of using `nginx` with reverse-proxy config, setting up of Webhook will look like: - -```kotlin -requestsExecutor.setWebhook( - WEBHOOK_URL, - INTERNAL_PORT, - filter, - ENGINE_FACTORY -) -``` - -Here: - -* `WEBHOOK_URL` - the url which will be used by Telegram system to send updates -* `INTERNAL_PORT` - the port which will be used in bot for listening of updates -* `filter` - instance of [UpdatesFilter](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/updateshandlers/UpdatesFilter.kt), -which will be used to filter incoming updates -* `ENGINE_FACTORY` - used factory name, for example, `CIO` in case of usage `io.ktor:ktor-server-cio` as server engine +Anyway, all library are very typical inside of them. For example, any request in TelegramBotAPI look like +`requestsExecutor.execute(SomeRequest())`. diff --git a/TelegramBotAPI-extensions-api/README.md b/TelegramBotAPI-extensions-api/README.md new file mode 100644 index 0000000000..cb192ec5f2 --- /dev/null +++ b/TelegramBotAPI-extensions-api/README.md @@ -0,0 +1,75 @@ +# TelegramBotAPI + +[![Awesome Kotlin Badge](https://kotlin.link/awesome-kotlin.svg)](https://github.com/KotlinBy/awesome-kotlin) +[![Download](https://api.bintray.com/packages/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/images/download.svg) ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/_latestVersion) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI-extensions-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI-extensions-api) +[![Build Status](https://jenkins.insanusmokrassar.com/buildStatus/icon?job=TelegramBotAPI-extensions-api_master__publishing)](https://jenkins.insanusmokrassar.com/job/TelegramBotAPI-extensions-api_master__publishing/) + +## What is it? + +It is wrapper library for [TelegramBotAPI](../TelegramBotAPI/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 `TelegramBotAPI` 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.version`, which must be set up by developer. Available versions are presented on +[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api), next version is last published: + +[![Download](https://api.bintray.com/packages/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/images/download.svg) ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI-extensions-api/_latestVersion) + +### Maven + +Dependency config presented here: + +```xml + + com.github.insanusmokrassar + TelegramBotAPI-extensions-api + ${telegrambotapi-extensions-api.version} + +``` + +### Gradle + +To use last versions you will need to add one line in repositories block of your `build.gradle`: + +`jcenter()` or `mavenCentral()` + +And add next line to your dependencies block: + +```groovy +implementation "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_extensions_api_version" +``` + +or for old gradle: + +```groovy +compile "com.github.insanusmokrassar:TelegramBotAPI-extensions-api:$telegrambotapi_extensions_api_version" +``` + +## Example of usage and comparison with `TelegramBotAPI` + +As said in [TelegramBotAPI](../TelegramBotAPI/README.md#Requests), it is possible to use next syntax for requests: + +```kotlin +val requestsExecutor: RequestsExecutor = ... +requestsExecutor.execute(GetMe()) +``` + +This library offer a little bit another way for this: + +```kotlin +val bot: RequestsExecutor = ... +bot.getMe() +``` + +The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt) +request is +[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt). diff --git a/TelegramBotAPI/README.md b/TelegramBotAPI/README.md new file mode 100644 index 0000000000..b93ed650f8 --- /dev/null +++ b/TelegramBotAPI/README.md @@ -0,0 +1,204 @@ +# TelegramBotAPI + +[![Awesome Kotlin Badge](https://kotlin.link/awesome-kotlin.svg)](https://github.com/KotlinBy/awesome-kotlin) +[![Download](https://api.bintray.com/packages/insanusmokrassar/StandardRepository/TelegramBotAPI/images/download.svg) ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.insanusmokrassar/TelegramBotAPI) +[![Build Status](https://jenkins.insanusmokrassar.com/buildStatus/icon?job=TelegramBotAPI_master__publishing)](https://jenkins.insanusmokrassar.com/job/TelegramBotAPI_master__publishing/) + +## What is it? + +Library for Object-Oriented and type-safe work with Telegram Bot API. Most part of some specific solves or unuseful +moments are describing by official [Telegram Bot API](https://core.telegram.org/bots/api). + +## Compatibility + +This version compatible with [23th of January 2020 update of TelegramBotAPI (version 4.6)](https://core.telegram.org/bots/api#january-23-2020). +There is Telegram Passport API exception of implemented functionality, which was presented in +[August 2018 update of TelegramBotAPI](https://core.telegram.org/bots/api-changelog#august-27-2018) update. It will be implemented +as soon as possible. All APIs that are not included are presented +[wiki](https://github.com/InsanusMokrassar/TelegramBotAPI/wiki/Not-included-API). + +## 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.version`, which must be set up by developer. Available versions are presented on +[bintray](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI), next version is last published: + +[![Download](https://api.bintray.com/packages/insanusmokrassar/StandardRepository/TelegramBotAPI/images/download.svg) ](https://bintray.com/insanusmokrassar/StandardRepository/TelegramBotAPI/_latestVersion) + +Currently, last versions of library can be available from the Maven repository with errors (for the reason difficult in publishing +of signed artifacts in Bintray). You can: + +* Use earlier version (available version you can find +[here](https://mvnrepository.com/artifact/com.github.insanusmokrassar/TelegramBotAPI)) +* Add `jCenter` repository in build config + +### Maven + +Dependency config presented here: + +```xml + + com.github.insanusmokrassar + TelegramBotAPI + ${telegrambotapi.version} + +``` + +### Gradle + +To use last versions you will need to add one line in repositories block of your `build.gradle`: + +`jcenter()` or `mavenCentral()` + +And add next line to your dependencies block: + +```groovy +implementation "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version" +``` + +or for old gradle: + +```groovy +compile "com.github.insanusmokrassar:TelegramBotAPI:$telegrambotapi_version" +``` + +## How to work with library? + +For now, this library have no some API god-object. Instead of this, this library has several +important objects: + +* [RequestsExecutor](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/bot/RequestsExecutor.kt) +* [Requests](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests) +* [Types](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types) + +### Types + +Types declare different objects representation. For example, `Chat` for now represented as +interface and has several realisations: + +* `PrivateChat` +* `GroupChat` +* `SupergroupChat` +* `ChannelChat` + +Instead of common garbage with all information as in original [Chat](https://core.telegram.org/bots/api#chat), +here it was separated for more obvious difference between chats types and their possible content. + +The same principle work with a lot of others things in this Telegram bot API. + +### Requests + +Requests usually are very simple objects, but some of them are using their own +build factories. For example, the next code show, how to get information about bot: + +```kotlin +val requestsExecutor: RequestsExecutor = ... +requestsExecutor.execute(GetMe()) +``` + +Also there is an alternative syntax for requests (like `requestsExecutor.getMe()` in project +[TelegramBotAPI-extensions-api](../TelegramBotAPI-extensions-api/README.md)) + +The result type of [GetMe (and getMe extension)](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/GetMe.kt) +request is +[ExtendedBot](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/User.kt). + +### RequestsExecutor + +It is base object which can be used to execute requests in API. For now by default included Ktor +realisation of `RequestsExecutor`, but it is possible, that in future it will be extracted in separated +project. How to create `RequestsExecutor`: + +```kotlin +val requestsExecutor = KtorRequestsExecutor( + TelegramAPIUrlsKeeper(TOKEN) +) +``` + +Here: + +* `KtorRequestsExecutor` - default realisation with [ktor](https://ktor.io) +* `TelegramAPIUrlsKeeper` - special keeper, which you can save and use for getting files full urls (`resolveFileURL` +extension inside of `PathedFile.kt`) +* `TOKEN` is just a token of bot which was retrieved according to +[instruction](https://core.telegram.org/bots#3-how-do-i-create-a-bot). + +By default, for JVM there is implemented `CIO` client engine, but there is not server engine. Both can be changed like +here: + +```groovy +dependencies { + // ... + implementation "io.ktor:ktor-server-cio:$ktor_version" // for implementing of server engine + implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine + // ... +} +``` + +You can avoid using of `server` dependency in case if you will not use `Webhook`s. In this case, +dependencies list will be simplify: + +```groovy +dependencies { + // ... + implementation "io.ktor:ktor-client-okhttp:$ktor_version" // for implementing of additional client engine + // ... +} +``` + +Here was used `okhttp` realisation of client, but there are several others engines for Ktor. More information +available on ktor.io site for [client](https://ktor.io/clients/http-client/engines.html) and [server](https://ktor.io/quickstart/artifacts.html) +engines. + +## Getting updates + +In this library currently realised two ways to get updates from telegram: + +* Polling - in this case bot will request updates from time to time (you can set up delay between requests) +* Webhook via reverse proxy or something like this + +### Updates filters + +Currently webhook method contains `UpdatesFilter` as necessary argument for getting updates. +`UpdatesFilter` will sort updates and throw their into different callbacks. Currently supporting +separate getting updates for media groups - they are accumulating with debounce in one second +(for being sure that all objects of media group was received). + +Updates polling also support `UpdatesFilter` but it is not required to use it and you can get updates directly +in `UpdateReceiver`, which you will provide to `startGettingOfUpdates` method + +### Webhook set up + +If you wish to use webhook method, you will need: + +* White IP - your IP address or host, which available for calling. [TelegramBotAPI](https://core.telegram.org/bots/api#setwebhook) +recommend to use some unique address for each bot which you are using +* SSL certificate. Usually you can obtain the certificate using your domain provider, [Let'sEncrypt](https://letsencrypt.org/) or [create it](https://core.telegram.org/bots/self-signed) +* Nginx or something like this + +Template for Nginx server config you can find in [this gist](https://gist.github.com/InsanusMokrassar/fcc6e09cebd07e46e8f0fdec234750c4#file-nginxssl-conf). + +For webhook you can provide `File` with public part of certificate, `URL` where bot will be available and inner `PORT` which +will be used to start receiving of updates. Actually, you can skip passing of `File` when you have something like +nginx for proxy forwarding. + +In case of using `nginx` with reverse-proxy config, setting up of Webhook will look like: + +```kotlin +requestsExecutor.setWebhook( + WEBHOOK_URL, + INTERNAL_PORT, + filter, + ENGINE_FACTORY +) +``` + +Here: + +* `WEBHOOK_URL` - the url which will be used by Telegram system to send updates +* `INTERNAL_PORT` - the port which will be used in bot for listening of updates +* `filter` - instance of [UpdatesFilter](https://github.com/InsanusMokrassar/TelegramBotAPI/blob/master/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/updateshandlers/UpdatesFilter.kt), +which will be used to filter incoming updates +* `ENGINE_FACTORY` - used factory name, for example, `CIO` in case of usage `io.ktor:ktor-server-cio` as server engine