add ChatEventsConversations and refill README of telegramboapi-extensions-utils

CHANGELOG.md

@@ -59,6 +59,11 @@
     * Expected class `MimeType` was added
         * Field `MimeTyped#mimeType` now typed by `MimeType` instead of `String`
     * `MediaGroupMemberInputMedia` children now can be deserialized (but only those ones who are declared inside library)
+* `TelegramBotAPI-extensions-utils`:
+    * Chat events splitters added:
+        * Extension `Flow<ChatEventMessage>#channelEvents` was added
+        * Extension `Flow<ChatEventMessage>#groupEvents` was added
+        * Extension `Flow<ChatEventMessage>#supergroupEvents` was added
 
 ### 0.27.1
 

TelegramBotAPI-extensions-utils/README.md

@@ -67,18 +67,64 @@ val filter = bot.startGettingUpdates(
 }
 ```
 
-### Getting of only text incoming messages
+### Filters
+
+There are several filters for flows.
+
+#### Sent messages
+
+All sent messages can be filtered for three types:
+
+| Type | Description | Flow extension |
+|:---- |:----------- |:-------------- |
+| Common messages | Simple messages with text, media, location, etc. | `asContentMessagesFlow` |
+| Chat actions | New chat member, rename of chat, etc. | `asChatEventsFlow` |
+| Unknown events | Any other messages, that contain unsupported data | `asUnknownMessagesFlow` |
+
+##### Common messages
+
+Unfortunately, due to the erasing of generic types, when you are using `asContentMessagesFlow` you will retrieve
+data with type `ContentMessage<*>`. For correct filtering of content type for retrieved objects, was created special
+filters:
+
+| Type | Result type | Flow extension |
+|:---- |:----------- |:-------------- |
+| Animation | `ContentMessage<AnimationContent>`| `onlyAnimationContentMessages` |
+| Audio | `ContentMessage<AudioContent>` | `onlyAudioContentMessages` |
+| Contact | `ContentMessage<ContactContent>` | `onlyContactContentMessages` |
+| Dice | `ContentMessage<DiceContent>` | `onlyDiceContentMessages` |
+| Document | `ContentMessage<DocumentContent>` | `onlyDocumentContentMessages` |
+| Game | `ContentMessage<GameContent>` | `onlyGameContentMessages` |
+| Invoice | `ContentMessage<InvoiceContent>` | `onlyInvoiceContentMessages` |
+| Location | `ContentMessage<LocationContent>` | `onlyLocationContentMessages` |
+| Photo | `ContentMessage<PhotoContent>` | `onlyPhotoContentMessages` |
+| Poll | `ContentMessage<PollContent>` | `onlyPollContentMessages` |
+| Sticker | `ContentMessage<StickerContent>` | `onlyStickerContentMessages` |
+| Text | `ContentMessage<TextContent>` | `onlyTextContentMessages` |
+| Venue | `ContentMessage<VenueContent>` | `onlyVenueContentMessages` |
+| Video | `ContentMessage<VideoContent>` | `onlyVideoContentMessages` |
+| VideoNote | `ContentMessage<VideoNoteContent>` | `onlyVideoNoteContentMessages` |
+| Voice | `ContentMessage<VoiceContent>` | `onlyVoiceContentMessages` |
+
+For example, if you wish to get only photo messages from private chats of groups, you should call next code:
 
 ```kotlin
-filter.asContentMessagesFlow().onlyTextContentMessages().onEach {
+filter.messageFlow.asContentMessagesFlow().onlyPhotoContentMessages().onEach {
     println(it.content)
-    println(it.fullEntitiesList())
 }.launchIn(
     CoroutineScope(Dispatchers.Default)
 )
 ```
 
-As a result, each received message which will be just text message will be printed out with full list of its internal entities
+##### Chat actions
+
+Chat actions can be divided for three types of events source:
+
+| Type | Flow extension |
+|:---- |:-------------- |
+| Channel events | `channelEvents` |
+| Group events | `groupEvents` |
+| Supergroup events | `supergroupEvents` |
 
 ## Shortcuts
 

TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/ChatEventsConversations.kt

@@ -0,0 +1,21 @@
+package com.github.insanusmokrassar.TelegramBotAPI.extensions.utils
+
+import com.github.insanusmokrassar.TelegramBotAPI.types.message.*
+import com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ChatEventMessage
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.mapNotNull
+import kotlin.reflect.KClass
+
+
+fun <T : ChatEventMessage> Flow<ChatEventMessage>.divideBySource(contentType: KClass<T>) = mapNotNull {
+    if (contentType.isInstance(it)) {
+        @Suppress("UNCHECKED_CAST")
+        it as T
+    } else {
+        null
+    }
+}
+
+fun Flow<ChatEventMessage>.channelEvents() = divideBySource(ChannelEventMessage::class)
+fun Flow<ChatEventMessage>.groupEvents() = divideBySource(GroupEventMessage::class)
+fun Flow<ChatEventMessage>.supergroupEvents() = divideBySource(SupergroupEventMessage::class)