@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-android-v6-push/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: cometchat-android-v6-push
+description: "CometChat Android UIKit v6 push notifications — FCM setup, chat/call notification handling, VoIP integration, and deep-linking"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x / com.cometchat:chatuikit-kotlin-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, push, fcm, firebase, voip, notifications, calls"
+---
+
+> **Companion skills:** cometchat-android-v6-core (init/login), cometchat-android-v6-events (call events), cometchat-android-v6-builder-settings (calling config)
+
+## Purpose
+
+Set up push notifications for CometChat v6 using Firebase Cloud Messaging (FCM), handle chat and call notifications, and integrate VoIP for background call handling.
+
+## Use this skill when
+
+- Adding FCM push notifications for chat messages
+- Handling incoming call notifications (foreground and background)
+- Setting up VoIP with TelecomManager for native call UI
+- Implementing deep-link navigation from notifications
+
+## Do not use this skill when
+
+- Just initializing the SDK (use `cometchat-android-v6-core`)
+- Working with UI components (use `cometchat-*-components`)
+
+## 1. FCM Setup
+
+### 1.1 Gradle Dependencies
+
+```kotlin
+// In project-level build.gradle
+plugins {
+    id("com.google.gms.google-services") version "4.4.2" apply false
+}
+
+// In app-level build.gradle.kts
+plugins {
+    id("com.google.gms.google-services")
+}
+
+dependencies {
+    implementation(platform("com.google.firebase:firebase-bom:33.x.x"))
+    implementation("com.google.firebase:firebase-messaging")
+}
+```
+
+Add `google-services.json` to your app module's root directory.
+
+### 1.2 Initialize Firebase
+
+```kotlin
+// In Application.onCreate()
+FirebaseApp.initializeApp(this)
+```
+
+## 2. FCMService Implementation
+
+> **Heads-up — this is a reference pattern.** The classes referenced below (`CometChatVoIP`, `CometChatVoIPConnectionService`, `FCMMessageDTO`, `FCMCallDto`, `FCMService`, `VoIPPermissionListener`, `CometChatVoIPUtils`, `FCMMessageNotificationUtils`) are NOT exported from `com.cometchat:chatuikit-{compose,kotlin}-android:6.x`. They live in the `master-app-jetpack` sample app — copy the relevant source files into your project, or use them as a guide for writing your own equivalents. The kit's only public push surface is `CometChatNotifications.registerPushToken(...)` / `unregisterPushToken(...)`; everything below is glue you control.
+
+Pattern from `master-app-jetpack/fcm/FCMService.kt` (sample-app code, copy into your project):
+
+```kotlin
+class FCMService : FirebaseMessagingService() {
+
+    companion object {
+        var fcmToken: String? = null
+            private set
+    }
+
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        fcmToken = token
+        // Store token for later use (e.g., SharedPreferences)
+    }
+
+    override fun onMessageReceived(message: RemoteMessage) {
+        super.onMessageReceived(message)
+
+        if (message.data.isEmpty()) return
+
+        val type = message.data["type"]?.lowercase()
+        when (type) {
+            "chat" -> handleChatNotification(message)
+            "call" -> handleCallNotification(message)
+        }
+    }
+}
+```
+
+### 2.1 Chat Notification Handling
+
+```kotlin
+private fun handleChatNotification(message: RemoteMessage) {
+    val fcmMessageDTO = Gson().fromJson(
+        Gson().toJson(message.data),
+        FCMMessageDTO::class.java
+    )
+
+    // Mark as delivered for read receipts (only if SDK is initialized)
+    if (CometChatUIKit.isSDKInitialized()) {
+        CometChat.markAsDelivered(
+            fcmMessageDTO.tag!!.toLong(),
+            fcmMessageDTO.sender!!,
+            fcmMessageDTO.receiverType!!,
+            fcmMessageDTO.receiver!!
+        )
+    }
+
+    // Show notification if user is NOT in the same chat
+    val isUser = fcmMessageDTO.receiverType == CometChatConstants.RECEIVER_TYPE_USER
+    val uid = if (isUser) fcmMessageDTO.sender!! else fcmMessageDTO.receiver!!
+
+    if (uid != currentOpenChatId) {
+        // Build and show notification
+        FCMMessageNotificationUtils.showNotification(
+            this, fcmMessageDTO, intent,
+            NOTIFICATION_KEY_REPLY_ACTION,
+            NotificationCompat.CATEGORY_MESSAGE
+        )
+    }
+}
+```
+
+### 2.2 Call Notification Handling
+
+```kotlin
+private fun handleCallNotification(message: RemoteMessage) {
+    val sessionId = message.data["sessionId"]
+    val callAction = message.data["callAction"]
+
+    // CRITICAL: Check if SDK is initialized
+    if (!CometChatUIKit.isSDKInitialized()) {
+        return // Cannot handle call without SDK
+    }
+
+    // Check VoIP permissions
+    if (!CometChatVoIP.hasReadPhoneStatePermission(this) ||
+        !CometChatVoIP.hasManageOwnCallsPermission(this) ||
+        !CometChatVoIP.hasAnswerPhoneCallsPermission(this)) {
+        return
+    }
+
+    // Check phone account is enabled
+    CometChatVoIP.hasEnabledPhoneAccountForVoIP(this, object : VoIPPermissionListener {
+        override fun onPermissionsGranted() {
+            handleCallFlow(message)
+        }
+        override fun onPermissionsDenied(error: CometChatVoIPError?) {
+            // Cannot show VoIP UI
+        }
+    })
+}
+```
+
+## 3. VoIP Integration
+
+### 3.1 Required Permissions
+
+```xml
+<uses-permission android:name="android.permission.READ_PHONE_STATE" />
+<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
+<uses-permission android:name="android.permission.ANSWER_PHONE_CALLS" />
+```
+
+### 3.2 VoIP Call Flow
+
+```kotlin
+private fun handleCallFlow(message: RemoteMessage) {
+    val callData = Gson().fromJson(
+        Gson().toJson(message.data),
+        FCMCallDto::class.java
+    )
+
+    // Initialize VoIP
+    CometChatVoIP.init(this, applicationInfo.loadLabel(packageManager).toString())
+
+    when (callData.callAction) {
+        "initiated" -> {
+            // Show incoming call UI (only if app is in background)
+            if (!isAppInForeground()) {
+                voipIncomingCall(callData)
+            }
+            // If foreground, UIKit's CometChatIncomingCall handles it
+        }
+        "cancelled", "unanswered" -> {
+            // End the native call UI if session matches
+            if (CometChatVoIPUtils.currentSessionId == callData.sessionId) {
+                CometChatVoIP.telecomManager?.endCall()
+            }
+        }
+    }
+}
+```
+
+### 3.3 Foreground vs Background Routing
+
+| App State | Incoming Call Handler |
+|---|---|
+| Foreground | UIKit's `CometChatIncomingCall` via SDK call listener |
+| Background | VoIP via `TelecomManager` + `CometChatVoIPConnectionService` |
+| Killed | FCM wakes app, but SDK may not be initialized — cannot handle call |
+
+### 3.4 Busy Rejection
+
+```kotlin
+private fun rejectCallWithBusyStatus(call: Call) {
+    CometChat.rejectCall(
+        call.sessionId,
+        CometChatConstants.CALL_STATUS_BUSY,
+        object : CometChat.CallbackListener<Call>() {
+            override fun onSuccess(rejectedCall: Call?) {
+                rejectedCall?.let {
+                    CometChatEvents.emitCallEvent(CometChatCallEvent.CallRejected(it))
+                }
+            }
+            override fun onError(e: CometChatException) { }
+        }
+    )
+}
+```
+
+## 4. AndroidManifest Registration
+
+```xml
+<service
+    android:name=".fcm.FCMService"
+    android:exported="false">
+    <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+    </intent-filter>
+</service>
+
+<!-- VoIP Connection Service -->
+<service
+    android:name=".voip.CometChatVoIPConnectionService"
+    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.telecom.ConnectionService" />
+    </intent-filter>
+</service>
+```
+
+## 5. WebSocket Connection Management
+
+From `master-app-jetpack/Application.kt` — manage WebSocket connections based on app lifecycle:
+
+```kotlin
+// When app comes to foreground
+CometChat.connect(object : CometChat.CallbackListener<String?>() {
+    override fun onSuccess(s: String?) { /* connected */ }
+    override fun onError(e: CometChatException) { /* failed */ }
+})
+
+// When app goes to background
+CometChat.disconnect(object : CometChat.CallbackListener<String?>() {
+    override fun onSuccess(s: String?) { /* disconnected */ }
+    override fun onError(e: CometChatException) { /* failed */ }
+})
+```
+
+## Hard rules
+
+- ALWAYS check `CometChatUIKit.isSDKInitialized()` before making SDK calls in FCM service — the app may have been killed
+- NEVER show VoIP incoming call UI when app is in foreground — UIKit's `CometChatIncomingCall` handles foreground calls
+- VoIP requires READ_PHONE_STATE, MANAGE_OWN_CALLS, and ANSWER_PHONE_CALLS permissions — check all three before handling calls
+- `CometChat.markAsDelivered()` requires the SDK to be initialized — skip it if not
+- For push token registration, use `CometChatNotifications.registerPushToken(...)` / `unregisterPushToken(...)` — that is the kit's only public push API. The `CometChatVoIP*` / `FCM*` classes shown above are sample-app glue (`master-app-jetpack`), not part of `chatuikit-{compose,kotlin}`
+- Always manage WebSocket connections based on app lifecycle to avoid battery drain

package/skills/cometchat-android-v6-testing/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: cometchat-android-v6-testing
+description: "CometChat Android UIKit v6 testing — unit testing ViewModels, Compose UI testing, Espresso, Maestro, and CI configuration"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x / com.cometchat:chatuikit-kotlin-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, testing, junit, kotest, compose-testing, espresso, maestro"
+---
+
+> **Companion skills:** cometchat-android-v6-extensions (ViewModel/DataSource architecture), cometchat-android-v6-compose-components, cometchat-android-v6-kotlin-components
+
+## Purpose
+
+Test CometChat UIKit v6 components and ViewModels — unit tests for the shared core module, Compose UI tests, Espresso tests for Views, and end-to-end tests with Maestro.
+
+## Use this skill when
+
+- Writing unit tests for CometChat ViewModels
+- Writing Compose UI tests for CometChat components
+- Writing Espresso tests for Kotlin Views components
+- Setting up Maestro flows for end-to-end testing
+- Configuring CI for CometChat test suites
+
+## Do not use this skill when
+
+- Debugging runtime issues (use `cometchat-android-v6-troubleshooting`)
+- Working with component APIs (use `cometchat-*-components`)
+
+## 1. Test Dependencies
+
+From `chatuikit-compose/build.gradle.kts`:
+
+```kotlin
+dependencies {
+    // Unit testing
+    testImplementation("junit:junit:4.13.2")
+    testImplementation("io.kotest:kotest-runner-junit5:5.x")
+    testImplementation("io.kotest:kotest-assertions-core:5.x")
+    testImplementation("io.kotest:kotest-property:5.x")
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.x")
+    testImplementation("androidx.arch.core:core-testing:2.x")
+    testImplementation("androidx.lifecycle:lifecycle-runtime-testing:2.x")
+    testImplementation("org.mockito:mockito-core:5.x")
+    testImplementation("org.mockito.kotlin:mockito-kotlin:5.x")
+
+    // Android instrumented testing
+    androidTestImplementation("androidx.test.ext:junit:1.x")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.x")
+    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
+    androidTestImplementation(platform("androidx.compose:compose-bom:2024.x.x"))
+
+    // Debug-only Compose tooling
+    debugImplementation("androidx.compose.ui:ui-tooling")
+    debugImplementation("androidx.compose.ui:ui-test-manifest")
+}
+```
+
+Enable JUnit Platform for Kotest:
+
+```kotlin
+android {
+    testOptions {
+        unitTests.all {
+            it.useJUnitPlatform()
+        }
+    }
+}
+```
+
+## 2. Unit Testing ViewModels
+
+ViewModels live in `chatuikit-core` and are shared across both stacks. Test them with coroutines-test and Mockito:
+
+```kotlin
+import kotlinx.coroutines.test.runTest
+import org.mockito.kotlin.mock
+import org.mockito.kotlin.whenever
+
+class CometChatConversationsViewModelTest {
+
+    @Test
+    fun `loadConversations emits success state`() = runTest {
+        val mockDataSource = mock<ConversationListDataSource>()
+        // Setup mock responses...
+
+        val viewModel = CometChatConversationsViewModel(/* inject mocks */)
+
+        // Collect state and assert
+        viewModel.uiState.test {
+            val state = awaitItem()
+            // Assert state is success with expected data
+        }
+    }
+}
+```
+
+### 2.1 Testing Events
+
+```kotlin
+import com.cometchat.uikit.core.events.CometChatEvents
+import com.cometchat.uikit.core.events.CometChatMessageEvent
+
+@Test
+fun `emitting message event is received by collector`() = runTest {
+    val events = mutableListOf<CometChatMessageEvent>()
+
+    val job = launch {
+        CometChatEvents.messageEvents.collect { events.add(it) }
+    }
+
+    CometChatEvents.emitMessageEventSync(
+        CometChatMessageEvent.MessageSent(mockMessage, MessageStatus.SUCCESS)
+    )
+
+    advanceUntilIdle()
+    assertEquals(1, events.size)
+    job.cancel()
+}
+```
+
+## 3. Compose UI Testing
+
+```kotlin
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performClick
+
+class CometChatConversationsTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun conversationsList_displaysTitle() {
+        composeTestRule.setContent {
+            CometChatTheme {
+                CometChatConversations()
+            }
+        }
+
+        // Assert UI elements
+        composeTestRule.onNodeWithText("Chats").assertExists()
+    }
+
+    @Test
+    fun conversationItem_clickNavigates() {
+        var clickedConversation: Conversation? = null
+
+        composeTestRule.setContent {
+            CometChatTheme {
+                CometChatConversations(
+                    onItemClick = { clickedConversation = it }
+                )
+            }
+        }
+
+        // Interact and assert
+        // composeTestRule.onNodeWithText("User Name").performClick()
+        // assertNotNull(clickedConversation)
+    }
+}
+```
+
+## 4. Espresso Testing (Kotlin Views)
+
+```kotlin
+import androidx.test.espresso.Espresso.onView
+import androidx.test.espresso.assertion.ViewAssertions.matches
+import androidx.test.espresso.matcher.ViewMatchers.*
+import androidx.test.ext.junit.rules.ActivityScenarioRule
+
+class ConversationsActivityTest {
+
+    @get:Rule
+    val activityRule = ActivityScenarioRule(ConversationsActivity::class.java)
+
+    @Test
+    fun conversationsList_isDisplayed() {
+        onView(withId(R.id.conversations))
+            .check(matches(isDisplayed()))
+    }
+}
+```
+
+## 5. Property-Based Testing with Kotest
+
+The project uses Kotest for property-based tests (e.g., `MessageAdapterPropertyTest.kt`):
+
+```kotlin
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.property.forAll
+import io.kotest.property.Arb
+import io.kotest.property.arbitrary.string
+
+class BubbleFactoryKeyTest : FunSpec({
+
+    test("factory key format is always category_type") {
+        forAll(Arb.string(1..20), Arb.string(1..20)) { category, type ->
+            val key = BubbleFactory.getKey(category, type)
+            key == "${category}_${type}"
+        }
+    }
+})
+```
+
+## 6. Maestro End-to-End Testing
+
+The `master-app-jetpack/ai-testing/` directory contains Maestro test configurations:
+
+```yaml
+# maestro/login_flow.yaml
+appId: com.example.jetpackuikit
+---
+- launchApp
+- tapOn: "Login"
+- inputText: "superhero1"
+- tapOn: "Submit"
+- assertVisible: "Chats"
+```
+
+Run with:
+
+```bash
+maestro test maestro/login_flow.yaml
+```
+
+## 7. CI Configuration
+
+### 7.1 GitHub Actions
+
+```yaml
+name: Test
+on: [push, pull_request]
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - run: ./gradlew testDebugUnitTest
+
+  instrumented-tests:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          script: ./gradlew connectedDebugAndroidTest
+```
+
+## 8. Test Organization
+
+| Test Type | Location | Framework | What to Test |
+|---|---|---|---|
+| Unit tests | `chatuikit-core/src/test/` | JUnit + Kotest + Mockito | ViewModels, DataSources, Repositories, Events |
+| Unit tests | `chatuikit-compose/src/test/` | JUnit + Kotest | BubbleFactory, style resolution |
+| Compose UI tests | `chatuikit-compose/src/androidTest/` | Compose Test | Component rendering, interactions |
+| Views UI tests | `chatuikit-kotlin/src/androidTest/` | Espresso | Component rendering, interactions |
+| E2E tests | `master-app-*/ai-testing/` | Maestro | Full user flows |
+
+## Hard rules
+
+- ALWAYS use `CometChatTheme {}` wrapper in Compose test `setContent` blocks — components depend on CompositionLocal values
+- Use `runTest` from `kotlinx-coroutines-test` for testing coroutines and SharedFlow
+- Use `useJUnitPlatform()` in test options for Kotest compatibility
+- Mock DataSources and Repositories when unit testing ViewModels — do NOT make real SDK calls in tests
+- CometChat SDK must NOT be initialized in unit tests — mock all SDK interactions
+- For Compose UI tests, use `createComposeRule()` not `createAndroidComposeRule()` unless you need Activity context