Merge pull request #4 from akrafts-gpt/master

Version 1.8.56

Author: alexey-kravtsov-tc

.github/workflows/sample-app-release.yml

@@ -0,0 +1,102 @@
+name: Sample app release build
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TELEGRAM_APP_ID: ${{ secrets.TELEGRAM_APP_ID }}
+      TELEGRAM_APP_HASH: ${{ secrets.TELEGRAM_APP_HASH }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
+      - name: Build Release APK
+        run: ./gradlew --no-daemon clean :sample:app:assembleRelease
+
+      - name: Upload Build Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-artifacts
+          path: sample/app/build/outputs/apk/release/app-release.apk
+          retention-days: 1
+
+  distribute:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download Build Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: release-artifacts
+          path: sample/app/build/outputs/apk/release
+
+      - name: Install Firebase CLI
+        run: |
+          npm install -g firebase-tools
+          firebase --version
+
+      - name: Upload to Firebase (Manual CLI)
+        env:
+          FIREBASE_APP_ID: ${{ secrets.FIREBASE_APP_ID }}
+          CREDENTIAL_CONTENT: ${{ secrets.FIREBASE_CREDENTIAL_FILE_CONTENT }}
+          GOOGLE_APPLICATION_CREDENTIALS: service-account.json
+        run: |
+          echo "$CREDENTIAL_CONTENT" > service-account.json
+          
+          # CHANGED: Explicitly using app-release.apk
+          APK_PATH="sample/app/build/outputs/apk/release/app-release.apk"
+
+          if [ ! -f "$APK_PATH" ]; then
+            echo "Error: APK not found at $APK_PATH"
+            ls -R sample/app/build/outputs/apk/
+            exit 1
+          fi
+
+          # 2. LOGIC: Determine release notes based on event type
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            NOTES="PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }}"
+          else
+            NOTES="Master Release: ${{ github.sha }}"
+          fi
+
+          firebase appdistribution:distribute "$APK_PATH" \
+            --app "$FIREBASE_APP_ID" \
+            --groups "testers" \
+            --release-notes "$NOTES" \
+            --debug
+
+      - name: Publish GitHub release
+        if: github.event_name == 'push'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: release-${{ github.run_number }}
+          name: Release build #${{ github.run_number }}
+          body: |
+            Automated Release build for commit ${{ github.sha }} on master.
+            This release contains the sample Compose client APK built from sample/app's Release variant.
+          prerelease: false
+          files: sample/app/build/outputs/apk/release/app-release.apk
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -89,6 +89,7 @@ hs_err_pid*
 bin/
 gen/
 release/
+build/
 
 # Gradle files
 .gradle/

Readme.md

@@ -1,67 +1,81 @@
-# Telegram Flow
+# Telegram Flow for TDLib
 
-Kotlin Coroutines extensions for Telegram API [TDLib](https://github.com/tdlib/td) (Telegram Database
- library)
+[![](hhttps://jitpack.io/v/akrafts-gpt/td-ktx.svg)](https://jitpack.io/v/#akrafts-gpt/td-ktx)
 
-## Using library
+Telegram Flow is a Kotlin-first extension toolkit for [TDLib](https://github.com/tdlib/td) that turns callback-based Telegram API calls into coroutines and flows. It keeps your client code concise while exposing idiomatic Compose- and coroutine-friendly APIs.
 
-The main class of the library is [TelegramFlow]. It converts Telegram Updates handlers to the
-Kotlin Coroutine Flows and Telegram callback-style Functions to Kotlin Coroutine suspend functions
+## Features
+- **Coroutine wrappers** for every TDLib function so you can `suspend` instead of juggling callbacks.
+- **Flow-based updates** that emit strongly typed Telegram updates with sensible defaults.
+- **Extension interfaces** to organize API access around Telegram entities (users, chats, messages, etc.).
+- **Compose-ready**: works seamlessly with `ViewModel` scopes and state flows.
 
-### Start using
+## Setup
+Add the library dependency from Maven Central:
 
-1. Create instance of [TelegramFlow]
-2. You can collect flow of TdApi.Objects from the TelegramFlow instance and its [flow extensions].
-3. Call [attachClient] function of the [TelegramFlow] instance to connect it to the Telegram Client.
-4. Now you can use numerous [extension functions] to send data to the Telegram API and collect data
- from [flow extensions]
- 
-### Using Flows
+```kotlin
+implementation(project(":libtd-ktx"))
+```
 
-[Any update](https://core.telegram.org/tdlib/getting-started#handling-updates) listed in TdApi can be collected by corresponding flow extension of the [TelegramFlow].
+The `libtd-ktx` module exposes TDLib (`com.github.tdlibx:td:1.8.56`) as an API dependency, so no extra TDLib declaration is required.
 
-```Kotlin
-telegramFlow.userStatusFlow().collect { status: TdApi.UpdateUserStatus ->
-    // collect UpdateUserStatus from Telegram
-}
-```
+The project ships a TDLib wrapper module (`libtd-ktx`) and a Compose sample under `sample/` that demonstrates usage with Hilt and the Navigation 3 typed destination APIs.
 
-For the Updates where there is the only field available inside, Update class is suppress by the flow extension and return data itself, for example: 
+## Getting started
+1. Create a single `TelegramFlow` instance and keep it in a long-lived scope (e.g., via DI).
+2. Attach a TDLib client once at startup:
 
-```Kotlin 
-telegramFlow.authorizationStateFlow().collect { state: TdApi.AuthorizationState ->
-    // collect AuthorizationState instead of TdApi.UpdateAuthorizationState since there is no other data inside
+```kotlin
+val telegramFlow = TelegramFlow()
+telegramFlow.attachClient()
+```
+
+3. Provide required TDLib parameters when prompted by the authorization state flow:
+
+```kotlin
+telegramFlow.authorizationStateFlow().collect { state ->
+    if (state is TdApi.AuthorizationStateWaitTdlibParameters) {
+        telegramFlow.setTdlibParameters(
+            databaseDirectory = "/data/user/0/<your.package>/files/td",
+            apiId = BuildConfig.TELEGRAM_APP_ID,
+            apiHash = BuildConfig.TELEGRAM_APP_HASH,
+            // ...other parameters
+        )
+    }
 }
 ```
 
-### Using Functions
+4. Send authentication information with coroutine calls:
 
-[Any funcrion](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html) listed in TdApi can be called via corresponding coroutine extension
+```kotlin
+telegramFlow.setAuthenticationPhoneNumber(phone, null)
+telegramFlow.checkAuthenticationCode(code)
+telegramFlow.checkAuthenticationPassword(password)
+```
+
+## Collecting updates
+Every TDLib update has a matching flow extension. Example: tracking user presence changes.
 
-```Kotlin
-suspend fun sendCode(code: String) {
-    api.checkAuthenticationCode(code) // send TdApi.CheckAuthenticationCode(code) to the Client
+```kotlin
+telegramFlow.userStatusFlow().collect { status ->
+    val user = telegramFlow.getUser(status.userId)
+    // update UI with latest user status
 }
 ```
 
-### Using extensions interfaces
+For updates that only wrap a single value, the flow returns the inner type directly, e.g. `authorizationStateFlow()` emits `TdApi.AuthorizationState` instances.
 
-Library provides [extension interfaces](https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.extensions/index.html) to access specific Telegram Object's extensions. This allows you to use the library full potential
+## Calling Telegram functions
+Each TDLib function is exposed as a suspending extension on `TelegramFlow`:
 
-```Kotlin
-class YourTelegramClass : UserKtx {
-    // Instance of the TelegramFlow connecting extensions to the API 
-    override val api = TelegramFlow()
-    // Flow that returns updates of the user as a full UserInfo
-    val fullInfoFlow: Flow<TdApi.UserFullInfo> = api.userFlow().map { user ->
-        user.getFullInfo() // call TdApi.GetUserFullInfo(userId) with id of the user instance
-    }
-}
+```kotlin
+suspend fun fetchSelf(): TdApi.User = telegramFlow.getMe()
 ```
-All possible extensions for Telegram entities can be accessed via [TelegramKtx]. List and description of available extension interfaces can be found [here](https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.extensions/index.html)
 
-[TelegramFlow]: https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.core/-telegram-flow/index.html
-[flow extensions]: https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.flows/index.html
-[attachClient]: https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.core/-telegram-flow/attach-client.html
-[extension functions]: https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.coroutines/index.html
-[TelegramKtx]: https://tdlibx.github.io/td-ktx/docs/libtd-ktx/kotlinx.telegram.extensions/-telegram-ktx/index.html
+Explore the full API surface in the [generated docs](https://tdlibx.github.io/td-ktx/docs/libtd-ktx/).
+
+## Samples
+A minimal Compose sample lives in [`sample/app`](sample/app). It wires `TelegramFlow` with Hilt, demonstrates handling the authorization flow, and renders online users with Navigation Compose.
+
+## License
+This project is distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for details.