update readmes

GiftsBot/README.md

@@ -0,0 +1,46 @@
+# GiftsBot
+
+Demonstrates the paginated owned-gift APIs by listing gifts for the chat in which the command is received.
+
+## Behavior
+
+At startup the bot prints its `getMe` result, then receives updates through long polling. While handling `/start`, it
+shows a typing action, retrieves every page of gifts, and chooses the request from the command chat type:
+
+- a business chat uses the business connection ID and requests the connected business account's gifts;
+- a private chat requests that user's gifts;
+- a public or unknown chat type requests that chat's gifts.
+
+Regular gifts are shown with their ID, optional text, and Stars cost. Unique gifts are shown with their optional ID,
+name, model, and number. Long results are split into multiple Telegram messages; an empty result produces
+`This chat have no any gifts`.
+
+## Command
+
+- `/start` — lists the owned gifts selected by the current chat type. It must be the only command in the message and
+  takes no arguments.
+
+Other commands and non-command messages are ignored.
+
+## Setup and permissions
+
+1. Create a bot with BotFather and obtain its token.
+2. For private-chat use, have the user start the bot so it can receive `/start` and reply.
+3. For group or channel use, add the bot and allow it to receive the command and send messages in that chat.
+4. For business-chat use, enable the bot's Business/Secretary mode, connect it to the business account, and grant the
+   **View gifts and Stars** (`can_view_gifts_and_stars`) business right.
+
+The example performs no access checks or error recovery, so Telegram API or permission errors end that command
+handler.
+
+## Arguments and launch
+
+The first application argument is the required bot token. Optional, exact, case-sensitive flags may follow in either
+order: `debug` prints KSLog diagnostics to standard output, and `testServer` selects Telegram's Bot API test server.
+Unknown trailing arguments are ignored.
+
+From the repository root:
+
+```bash
+./gradlew :GiftsBot:run --args="<BOT_TOKEN>"
+```

GiftsBot/src/main/kotlin/GiftsBot.kt

@@ -25,6 +25,17 @@ import dev.inmo.tgbotapi.utils.buildEntities
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 
+/**
+ * Starts a long-polling bot whose standalone `/start` command lists all owned gifts for the current chat.
+ *
+ * Business chats are queried through their business connection, private chats through their user ID, and public or
+ * unknown chat types through their chat ID. Regular and unique gifts are rendered as formatted text and long results
+ * are split across replies. The bot also prints its [getMe] result at startup.
+ *
+ * @param args the bot token followed by optional, case-sensitive `debug` and `testServer` flags; unknown trailing
+ * arguments are ignored
+ * @throws NoSuchElementException when the required bot token is absent
+ */
 suspend fun main(vararg args: String) {
     val botToken = args.first()