update examples for ktgbotapi 37.0.0

CommunitiesBot/README.md

@@ -1,6 +1,6 @@
 # CommunitiesBot
 
-This long-polling example demonstrates Communities support introduced in Telegram Bot API 10.2: typed service events when a chat joins or leaves a community, and inspection of a chat's current community.
+This long-polling example demonstrates Communities support introduced in Telegram Bot API 10.2 and extended in 10.3: typed service events when a chat joins or leaves a community, an event when a user joins a chat from a community, and inspection of a chat's current community.
 
 ## Behavior, commands, and triggers
 
@@ -10,18 +10,21 @@ At startup, the bot calls `getMe` and prints its bot information. It also prints
 | --- | --- |
 | `community_chat_added` service message | `onCommunityChatAdded` logs the chat and community name/ID, sends a join notice, then calls `getChat` and logs its nullable `community`. |
 | `community_chat_removed` service message | `onCommunityChatRemoved` logs the chat and sends a leave notice. This event is fieldless, so it has no former-community details. |
+| `community_chat_joined` service message | `onCommunityChatJoined` logs the source community and replies with a welcome message. This means a user joined the current chat from a community; it is distinct from adding the chat itself to a community. |
 | `/community` | Calls `getChat` and replies with the current community name/ID, or says the chat is not in a community. |
 | `/wait_community_added` | Waits without a timeout for the next added event in the command's chat, then replies with the community name/ID. |
-| `/wait_community_removed` | Waits without a timeout for the next removed event in the command's chat, then replies with the chat ID. Its initial waiting reply currently says "added." |
+| `/wait_community_removed` | Waits without a timeout for the next removed event in the command's chat, then replies with the chat ID. |
+| `/wait_community_joined` | Waits without a timeout for the next user-from-community join event in the command's chat, then replies with the source community name/ID. |
 
 Commands use no positional arguments; other commands only appear in the generic update log. Each wait first sends a waiting reply, filters events with `sameChat`, and takes the first match.
 
 ## API concepts
 
 - `CommunityChatAdded` carries a `Community` with a `CommunityId` and name; `CommunityChatRemoved` carries no fields.
-- `onCommunityChatAdded` and `onCommunityChatRemoved` provide typed handlers for the service events.
+- `CommunityChatJoined` carries the community through which a user joined the current chat.
+- `onCommunityChatAdded`, `onCommunityChatRemoved`, and `onCommunityChatJoined` provide typed handlers for the service events.
 - `getChat(...).community` exposes the nullable community on `ExtendedChat` without a subtype cast.
-- `waitCommunityChatAddedEventsMessages` and `waitCommunityChatRemovedEventsMessages` expose typed event-message flows.
+- `waitCommunityChatAddedEventsMessages`, `waitCommunityChatRemovedEventsMessages`, and `waitCommunityChatJoinedEventsMessages` expose typed event-message flows.
 
 ## Telegram setup and permissions
 

CommunitiesBot/src/main/kotlin/CommunitiesBot.kt

@@ -7,13 +7,13 @@ import dev.inmo.tgbotapi.extensions.api.bot.getMe
 import dev.inmo.tgbotapi.extensions.api.chat.get.getChat
 import dev.inmo.tgbotapi.extensions.api.send.reply
 import dev.inmo.tgbotapi.extensions.api.send.send
-import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatAdded
 import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatAddedEventsMessages
-import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatRemoved
+import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatJoinedEventsMessages
 import dev.inmo.tgbotapi.extensions.behaviour_builder.expectations.waitCommunityChatRemovedEventsMessages
 import dev.inmo.tgbotapi.extensions.behaviour_builder.telegramBotWithBehaviourAndLongPolling
 import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommand
 import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommunityChatAdded
+import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommunityChatJoined
 import dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onCommunityChatRemoved
 import dev.inmo.tgbotapi.extensions.utils.extensions.sameChat
 import kotlinx.coroutines.CoroutineScope
@@ -25,10 +25,11 @@ import kotlinx.coroutines.flow.first
  * Starts a long-polling bot that demonstrates Telegram Communities.
  *
  * [onCommunityChatAdded] receives the joined [dev.inmo.tgbotapi.types.communities.Community], while
- * [onCommunityChatRemoved] receives a fieldless removal event. `/community` reads
- * [dev.inmo.tgbotapi.types.chat.ExtendedChat.community] with [getChat]. The two wait commands use
- * [waitCommunityChatAddedEventsMessages] and [waitCommunityChatRemovedEventsMessages] to take the first same-chat
- * event without a timeout. The bot prints its [getMe] result and every received update.
+ * [onCommunityChatRemoved] receives a fieldless removal event, while [onCommunityChatJoined] reports a user joining
+ * the chat from a community. `/community` reads
+ * [dev.inmo.tgbotapi.types.chat.ExtendedChat.community] with [getChat]. The three wait commands use typed event-message
+ * expectations to take the first same-chat event without a timeout. The bot prints its [getMe] result and every
+ * received update.
  *
  * @param args the bot token followed by the optional, case-sensitive `debug` and `testServer` flags; unknown trailing
  * arguments are ignored
@@ -72,6 +73,13 @@ suspend fun main(vararg args: String) {
             send(message.chat.id, "This chat has left its community")
         }
 
+        // community_chat_joined: a user joined this chat through a community
+        onCommunityChatJoined { message ->
+            val community = message.chatEvent.community
+            println("A user joined chat ${message.chat.id} from community '${community.name}' (id=${community.id.long})")
+            reply(message, "Welcome! You joined from the ${community.name} community.")
+        }
+
         // Inspect the current chat's community on demand
         onCommand("community") {
             val community = getChat(it.chat.id).community
@@ -94,11 +102,18 @@ suspend fun main(vararg args: String) {
 
         // Suspend until the next community-removed event message from this chat.
         onCommand("wait_community_removed") { origin ->
-            reply(origin, "Waiting for this chat to be added to a community...")
+            reply(origin, "Waiting for this chat to be removed from a community...")
             waitCommunityChatRemovedEventsMessages().filter { it.sameChat(origin) }.first()
             reply(origin, "Chat removed from its community (${origin.chat.id})")
         }
 
+        // Suspend until a user joins this chat from a community.
+        onCommand("wait_community_joined") { origin ->
+            reply(origin, "Waiting for somebody to join this chat from a community...")
+            val event = waitCommunityChatJoinedEventsMessages().filter { it.sameChat(origin) }.first().chatEvent
+            reply(origin, "A user joined from ${event.community.name} (id=${event.community.id.long})")
+        }
+
         allUpdatesFlow.subscribeSafelyWithoutExceptions(this) {
             println(it)
         }