@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-android-v5-calls/references/group-calls.md

@@ -1,205 +0,0 @@
-# Group calls — broadcast meeting pattern (Android V5)
-
-Group calls in CometChat use a **different signaling channel than 1:1 user calls**. The Ringing flow (`CometChat.initiateCall` → `onIncomingCallReceived` on peer) is **1:1 user only**. For groups, the kit broadcasts a **custom message of type `"meeting"`** to the group; receivers see a "Join meeting" card in `CometChatMessageList` (kit) or need an explicit `MessageListener.onCustomMessageReceived` (custom UI).
-
-By-design kit behavior. Same semantic across all CometChat kits — confirmed against the React Native kit source 2026-05-15.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/android/group-calls
-
----
-
-## Architecture
-
-```
-Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
-  │                                       │                              │
-  │ CometChatCallButtons sends a          │                              │
-  │ CustomMessage(GUID, GROUP, "meeting", │                              │
-  │   { callType, sessionId })            │                              │
-  ├──────────────────────────────────────>│                              │
-  │                                       │ onCustomMessageReceived      │
-  │                                       ├─────────────────────────────>│
-  │                                       │                              │
-  │ caller mounts CometChatOngoingCallActivity                            │
-  │ with sessionID = groupGuid            │  receiver taps Join          │
-  │                                       │  → joinSession(GUID)         │
-  ├──────────────────────────────────────>│ <─────────────────────────── │
-  │            ───── WebRTC session active (sessionId = group GUID) ─────│
-```
-
-| Channel | 1:1 user calls | Group calls |
-|---|---|---|
-| Signaling | `CometChat.initiateCall(call, callback)` | `CometChat.sendCustomMessage(message, callback)` (type="meeting") |
-| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` |
-| Session ID | server-generated unique | group's GUID (persistent) |
-| Ring/decline | yes — `acceptCall` / `rejectCall` | no — receivers join or ignore |
-| Auto-cancel timeout | yes (45s default) | no — meeting persists in chat history |
-
----
-
-## Hard rules
-
-1. **Group calls broadcast a custom message; they do NOT use the call listener.** Custom UI with only `CometChat.addCallListener` receives NOTHING for group meetings.
-2. **Session ID = group GUID.** Persistent, not auto-cancelled.
-3. **Joining = `CometChatCalls.joinSession(sessionId, sessionSettings, container, CallbackListener)`** — single-call shape (token generation internal). `startSession` is a deprecated v4 shim; use `joinSession`.
-4. **No `CometChat.endCall(sessionId)` for groups** — meeting messages have no call entity. Local `CallSession.getInstance().leaveSession()` only.
-5. **ConnectionService / VoIP push for group meetings is NOT built-in.** The CometChat dashboard's push provider routes meeting messages as regular FCM notifications, not as `ACTION_CALL`. Customers wanting ConnectionService-ring for group meetings must intercept the FCM data payload, construct a `Connection` manually, and route into telecom.
-
----
-
-## Caller side — kit-based
-
-```kotlin
-// Inside a chat surface, e.g. inside CometChatMessageHeader:
-val callButtons = CometChatCallButtons(this)
-callButtons.setGroup(group)
-// Tapping voice/video automatically:
-// - sends CustomMessage(GUID, GROUP, "meeting", { callType, sessionId })
-// - opens CometChatOngoingCallActivity with sessionID = group.guid
-```
-
-No additional code on the caller side. The kit signs the user up for the WebRTC session immediately.
-
-## Caller side — custom UI
-
-```kotlin
-import com.cometchat.chat.core.CometChat
-import com.cometchat.chat.models.CustomMessage
-import com.cometchat.chat.constants.CometChatConstants
-import org.json.JSONObject
-
-fun startGroupCall(groupGuid: String, callType: String /* "audio" | "video" */) {
-    val sessionId = groupGuid
-    val customData = JSONObject().apply {
-        put("callType", callType)
-        put("sessionId", sessionId)
-    }
-
-    val meetingMessage = CustomMessage(
-        groupGuid,
-        CometChatConstants.RECEIVER_TYPE_GROUP,
-        "meeting",
-        customData,
-    ).apply {
-        category = CometChatConstants.CATEGORY_CUSTOM
-        metadata = JSONObject().apply {
-            put("incrementUnreadCount", true)
-            put("pushNotification", "meeting")
-            put("callType", callType)
-            put("sessionId", sessionId)
-        }
-    }
-
-    CometChat.sendCustomMessage(meetingMessage, object : CometChat.CallbackListener<CustomMessage>() {
-        override fun onSuccess(p0: CustomMessage) {
-            // Caller navigates to OngoingCallActivity with sessionId
-            CometChatOngoingCallActivity.launch(this@CallerActivity, sessionId, callType)
-        }
-        override fun onError(p0: CometChatException) { /* surface error */ }
-    })
-}
-```
-
----
-
-## Receiver side — kit-based (auto-renders meeting card)
-
-If your group's chat surface uses `CometChatMessageList`, the kit renders the meeting `CustomMessage` as a "Join meeting" card. Tap → kit calls `getRTCToken` + opens `CometChatOngoingCallActivity` with `sessionID = group.guid`.
-
-```kotlin
-val messageList = CometChatMessageList(this)
-messageList.setGroup(group)
-// Meeting cards render automatically.
-```
-
-## Receiver side — custom UI (Kotlin Views / Compose — needs MessageListener)
-
-```kotlin
-private val GROUP_MEETING_LISTENER_ID = "APP_ROOT_GROUP_MEETING_LISTENER"
-
-CometChat.addMessageListener(GROUP_MEETING_LISTENER_ID, object : CometChat.MessageListener() {
-    override fun onCustomMessageReceived(msg: CustomMessage) {
-        if (msg.category != CometChatConstants.CATEGORY_CUSTOM) return
-        if (msg.type != "meeting") return
-
-        val customData = msg.customData ?: return
-        val sessionId = customData.optString("sessionId", msg.receiverUid)
-        val callType = customData.optString("callType", "video")
-        val fromUid = msg.sender.uid
-        val groupGuid = msg.receiverUid
-
-        // Switch to main thread for UI work
-        runOnUiThread {
-            // Show your custom incoming-meeting UI:
-            // - notification with "Join" action
-            // - or in-app banner / full-screen activity
-        }
-    }
-})
-
-// Tear down in onDestroy:
-override fun onDestroy() {
-    super.onDestroy()
-    CometChat.removeMessageListener(GROUP_MEETING_LISTENER_ID)
-}
-```
-
-Register in your `Application` class or main `Activity` AFTER login — same lifecycle constraint as the 1:1 `CallListener`.
-
----
-
-## Edge cases
-
-### Late joining
-
-Meeting messages persist in chat history. Tapping the card joins the live session — works even hours later, until everyone has left.
-
-### Cancelling / leaving
-
-Each participant leaves independently. No "cancel meeting" — the message stays in history.
-
-```kotlin
-CallSession.getInstance().leaveSession()
-// NO CometChat.endCall — meetings have no call entity
-```
-
-### Push notifications
-
-The meeting `CustomMessage` carries `metadata.pushNotification = "meeting"`. CometChat's push system delivers it as a regular FCM notification. To get ConnectionService-ringing for meetings, intercept the FCM data payload in `FirebaseMessagingService.onMessageReceived` and route to `TelecomManager` manually. Not auto-wired.
-
-### Mixed cohorts
-
-If one side uses the kit (auto-renders meeting card in `CometChatMessageList`) and the other uses custom Activity-based UI (no message listener), the custom side receives nothing. Both sides must align on listener strategy.
-
----
-
-## Anti-patterns
-
-1. **Only `CometChat.addCallListener` registered, expecting group calls to ring.** Won't fire. Add a `MessageListener` too.
-2. **`CometChat.endCall(sessionId)` after a group hangup.** No call entity exists — API errors. Use `CallSession.getInstance().leaveSession()` locally only.
-3. **`<CometChatIncomingCall>` overlay activity expected for group meetings.** It only listens to 1:1 channel.
-4. **Treating sessionId as ephemeral.** It IS the group's GUID. Persistent.
-5. **Sending `CustomMessage` without `metadata.pushNotification = "meeting"`.** Offline group members won't get any push.
-6. **Registering the `MessageListener` before login.** The SDK silently drops listeners registered pre-login. Wire AFTER login, as part of `CometChat.login`'s callback or `addCallListener` lifecycle.
-
----
-
-## Verification checklist
-
-- [ ] If using kit caller: `CometChatCallButtons.setGroup(group)` + voice/video tap initiates the meeting message
-- [ ] If using custom caller: `CometChat.sendCustomMessage` called with `type="meeting"`, `category=CATEGORY_CUSTOM`, `customData={callType, sessionId: groupGuid}`, `metadata.pushNotification="meeting"`
-- [ ] If using kit receiver: `CometChatMessageList` renders the meeting card with a "Join" CTA
-- [ ] If using custom receiver UI: `CometChat.addMessageListener` registered + filters `category==CATEGORY_CUSTOM && type=="meeting"`
-- [ ] Listener registered AFTER login, NOT before
-- [ ] On hangup: `CallSession.getInstance().leaveSession()` (NOT `CometChat.endCall`)
-- [ ] Late-joining works
-- [ ] FCM data payload routed to ConnectionService manually if OS-ring for meetings is desired
-
----
-
-## Pointers
-
-- `ringing-integration.md` — 1:1 user calls (different signaling channel)
-- `cometchat-android-v5-calls/SKILL.md` rules — V5 hard rules (calls-sdk-android peer dep, etc.)
-- Canonical docs: https://www.cometchat.com/docs/calls/android/group-calls
-- Reference impl (cross-platform semantic): `cometchat-react-calls/references/group-calls.md`

package/skills/cometchat-android-v5-calls/references/idle-timeout.md

@@ -1,117 +0,0 @@
-# Idle timeout on Android V5
-
-SDK API: SessionSettingsBuilder setter + listener event. ViewModel + StateFlow pattern (cf. `references/raise-hand.md`). Material AlertDialog or BottomSheet for the prompt.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/android/idle-timeout
-**Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts.
-
----
-
-## SDK API
-
-```kotlin
-import com.cometchat.calls.core.CometChatCalls
-import com.cometchat.calls.model.SessionType
-
-val settings = CometChatCalls.SessionSettingsBuilder()
-  .setSessionType(SessionType.VIDEO)
-  .setIdleTimeoutPeriod(60)   // SECONDS (= 60s). single setter — no before/after-prompt pair. default 300
-  .build()
-```
-
-> **⚠ Unit footgun — Android takes SECONDS, not milliseconds.** `setIdleTimeoutPeriod(int)` is in **seconds** (default `300` = 5 min; docs: calls/android/idle-timeout). This differs from the **web / React Native / Angular** Calls SDK, whose `SessionSettings.idleTimeoutPeriodBeforePrompt/AfterPrompt` are in **milliseconds**. Copying a web value like `60000` here sets a ~16.7-hour timeout, not 60 seconds. Use `60` for one minute.
-
-Listener — `onSessionTimedOut()` lives on `SessionStatusListener` in v5.
-Register on the `CallSession` instance from `joinSession`'s `onSuccess`:
-
-```kotlin
-import com.cometchat.calls.listeners.SessionStatusListener
-
-callSession.addSessionStatusListener(this, object : SessionStatusListener() {
-  override fun onSessionTimedOut() {
-    // Runs on background thread — dispatch to main
-    runOnUiThread {
-      Toast.makeText(this@CallActivity, "Call ended due to inactivity", Toast.LENGTH_LONG).show()
-      finish()  // or NavController.popBackStack()
-    }
-  }
-})
-```
-
----
-
-## ViewModel pattern
-
-```kotlin
-data class CallUiState(val timedOut: Boolean = false)
-
-class CallViewModel : ViewModel() {
-  private val _state = MutableStateFlow(CallUiState())
-  val state: StateFlow<CallUiState> = _state
-
-  fun onSessionTimedOut() {
-    _state.update { it.copy(timedOut = true) }
-  }
-}
-
-// Activity collects:
-lifecycleScope.launch {
-  repeatOnLifecycle(Lifecycle.State.STARTED) {
-    viewModel.state.collect { state ->
-      if (state.timedOut) {
-        showIdleTimeoutToast()
-        finish()
-      }
-    }
-  }
-}
-```
-
-The bridge is the listener calling `viewModel.onSessionTimedOut()` (cf. raise-hand.md ViewModel pattern).
-
----
-
-## Prompt UI — Material AlertDialog
-
-```kotlin
-fun showIdlePrompt(onStay: () -> Unit, onEnd: () -> Unit) {
-  MaterialAlertDialogBuilder(this)
-    .setTitle("Still there?")
-    .setMessage("You're alone in this call. It'll end in 60 seconds.")
-    .setCancelable(false)
-    .setPositiveButton("Stay") { _, _ -> onStay() }
-    .setNegativeButton("End now") { _, _ -> onEnd() }
-    .show()
-}
-```
-
-`setCancelable(false)` prevents back-button dismiss; user must explicitly choose.
-
----
-
-## Anti-patterns
-
-Web sister rules + Android-specific:
-
-1. **`Toast.makeText` from background thread.** Crashes — must be on main. `runOnUiThread { ... }` or `lifecycleScope.launch { ... }`.
-2. **Dialog without `setCancelable(false)`.** Back-button dismisses; the timer keeps running and disconnects without user response.
-3. **Listener attached to a Fragment that's been replaced.** Idle timeout fires after fragment destroyed → IllegalStateException. Detach listener in `onDestroyView`.
-
----
-
-## Verification checklist
-
-- [ ] SessionSettingsBuilder sets the idle period via `setIdleTimeoutPeriod(...)`
-- [ ] `onSessionTimedOut` dispatches to main thread (`runOnUiThread` or coroutine)
-- [ ] Dialog uses `setCancelable(false)`
-- [ ] Listener attached in `onCreate`/`onResume`, detached in matching teardown
-- [ ] Real-device smoke: 2 phones in call, hangup → other shows prompt after delay
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/idle-timeout.md` — sister reference
-- `cometchat-android-v5-calls` SKILL.md
-- `references/raise-hand.md` — ViewModel + StateFlow sibling pattern
-- Canonical docs: https://www.cometchat.com/docs/calls/android/idle-timeout

package/skills/cometchat-android-v5-calls/references/in-call-chat.md

@@ -1,134 +0,0 @@
----
-name: in-call-chat
-description: Add in-call messaging using CometChat Chat SDK and UI Kit. Use when implementing chat during calls, chat button, unread badge count, or group messaging linked to call session. Triggers on "in-call chat", "chat during call", "chat button", "in call messaging", "setChatButtonUnreadCount".
-inclusion: manual
----
-
-# CometChat Calls SDK v5 — In-Call Chat
-
-## Overview
-
-Add real-time text messaging during calls. Uses a CometChat Group (GUID = session ID) for chat. Requires Chat SDK + UI Kit alongside the Calls SDK.
-
-## Prerequisites
-
-- Calls SDK + Chat SDK + UI Kit integrated
-- Dependencies:
-  ```kotlin
-  implementation("com.cometchat:chat-sdk-android:4.0.+")
-  implementation("com.cometchat:calls-sdk-android:5.0.+")
-  implementation("com.cometchat:chat-uikit-android:4.+")
-  ```
-
-## Key Imports
-
-```kotlin
-import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.listeners.ButtonClickListener
-import com.cometchat.chat.core.CometChat
-import com.cometchat.chat.constants.CometChatConstants
-import com.cometchat.chat.models.Group
-```
-
-## Implementation
-
-### 1. Enable Chat Button
-
-```kotlin
-val sessionSettings = CometChatCalls.SessionSettingsBuilder()
-    .hideChatButton(false)  // show chat button (hidden by default)
-    .build()
-```
-
-### 2. Create/Join Chat Group
-
-Use session ID as group GUID:
-
-```kotlin
-private fun setupChatGroup(sessionId: String, meetingName: String) {
-    CometChat.getGroup(sessionId, object : CometChat.CallbackListener<Group>() {
-        override fun onSuccess(group: Group) {
-            if (!group.isJoined) {
-                CometChat.joinGroup(sessionId, group.groupType, null, /* listener */)
-            }
-        }
-        override fun onError(e: CometChatException) {
-            if (e.code == "ERR_GUID_NOT_FOUND") {
-                val group = Group(sessionId, meetingName, CometChatConstants.GROUP_TYPE_PUBLIC, null)
-                CometChat.createGroup(group, /* listener */)
-            }
-        }
-    })
-}
-```
-
-### 3. Handle Chat Button Click
-
-```kotlin
-var unreadCount = 0
-
-callSession.addButtonClickListener(this, object : ButtonClickListener() {
-    override fun onChatButtonClicked() {
-        unreadCount = 0
-        callSession.setChatButtonUnreadCount(0)
-        startActivity(Intent(this@CallActivity, ChatActivity::class.java).apply {
-            putExtra("SESSION_ID", sessionId)
-        })
-    }
-    // ... other overrides
-})
-```
-
-### 4. Track Unread Messages
-
-```kotlin
-CometChat.addMessageListener(TAG, object : CometChat.MessageListener() {
-    override fun onTextMessageReceived(textMessage: TextMessage) {
-        val receiver = textMessage.receiver
-        if (receiver is Group && receiver.guid == sessionId) {
-            unreadCount++
-            CallSession.getInstance().setChatButtonUnreadCount(unreadCount)
-        }
-    }
-})
-
-// Remove in onDestroy
-override fun onDestroy() {
-    CometChat.removeMessageListener(TAG)
-    super.onDestroy()
-}
-```
-
-### 5. Chat Activity (UI Kit)
-
-```kotlin
-class ChatActivity : AppCompatActivity() {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        setContentView(R.layout.activity_chat)
-        val sessionId = intent.getStringExtra("SESSION_ID") ?: return
-
-        CometChat.getGroup(sessionId, object : CometChat.CallbackListener<Group>() {
-            override fun onSuccess(group: Group) {
-                findViewById<CometChatMessageList>(R.id.message_list).setGroup(group)
-                findViewById<CometChatMessageComposer>(R.id.message_composer).setGroup(group)
-                findViewById<CometChatMessageHeader>(R.id.message_header).setGroup(group)
-            }
-            override fun onError(e: CometChatException) {}
-        })
-    }
-}
-```
-
-## Gotchas
-
-- Chat button is **hidden by default** — use `.hideChatButton(false)` to show it
-- The group GUID should match the session ID to link chat to the call
-- `setChatButtonUnreadCount()` updates the badge on the built-in chat button
-- Remove message listeners in `onDestroy()` to prevent leaks
-- UI Kit components (`CometChatMessageList`, etc.) require the UI Kit dependency
-- Create the group before or when joining the call — not after
-
-## Sample App Reference
-
-- `CallActivity.kt` — Session settings and button click listener setup

package/skills/cometchat-android-v5-calls/references/join-session.md

@@ -1,120 +0,0 @@
----
-name: join-session
-description: Join a CometChat call session using CometChatCalls.joinSession with SessionSettingsBuilder. Use when joining calls, configuring session settings, voice vs video calls, or generating tokens. Triggers on "join session", "join call", "start call", "SessionSettingsBuilder".
-inclusion: manual
----
-
-# CometChat Calls SDK v5 — Join Session
-
-## Overview
-
-Join a call session using `CometChatCalls.joinSession()`. Supports two approaches: direct session ID (simple) or manual token generation (advanced). Requires a `RelativeLayout` container and configured `SessionSettings`.
-
-## Prerequisites
-
-- Calls SDK initialized and user logged in
-- A valid session ID (from Chat SDK's `Call.sessionId` or your backend)
-- A `RelativeLayout` container in your layout XML
-
-## Key Imports
-
-```kotlin
-import com.cometchat.calls.core.CometChatCalls
-import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.model.SessionType
-import com.cometchat.calls.model.LayoutType
-import com.cometchat.calls.model.AudioMode
-import com.cometchat.calls.exceptions.CometChatException
-```
-
-## Implementation
-
-### Layout Container
-
-```xml
-<RelativeLayout
-    android:id="@+id/call_view_container"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent" />
-```
-
-### Join with Session ID (Recommended)
-
-```kotlin
-val callContainer = findViewById<RelativeLayout>(R.id.call_view_container)
-
-val sessionSettings = CometChatCalls.SessionSettingsBuilder()
-    .setTitle("Team Meeting")
-    .setSessionType(if (isVoiceCall) SessionType.VOICE else SessionType.VIDEO)
-    .setLayout(LayoutType.TILE)
-    .setAudioMode(if (isVoiceCall) AudioMode.EARPIECE else AudioMode.SPEAKER)
-    .startAudioMuted(false)
-    .startVideoPaused(isVoiceCall)
-    .build()
-
-CometChatCalls.joinSession(
-    sessionId,
-    sessionSettings,
-    callContainer,
-    object : CometChatCalls.CallbackListener<CallSession>() {
-        override fun onSuccess(callSession: CallSession) {
-            Log.d(TAG, "Joined session: $sessionId")
-            // Setup listeners on callSession
-        }
-        override fun onError(e: CometChatException) {
-            Log.e(TAG, "Failed to join: ${e.message}")
-        }
-    }
-)
-```
-
-### Join with Token (Advanced)
-
-```kotlin
-// Step 1: Generate token
-CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener<GenerateToken>() {
-    override fun onSuccess(token: GenerateToken) {
-        // Step 2: Join with token
-        CometChatCalls.joinSession(token, sessionSettings, callContainer,
-            object : CometChatCalls.CallbackListener<CallSession>() {
-                override fun onSuccess(callSession: CallSession) { /* joined */ }
-                override fun onError(e: CometChatException) { /* error */ }
-            }
-        )
-    }
-    override fun onError(e: CometChatException) { /* token error */ }
-})
-```
-
-### Voice Call vs Video Call
-
-```kotlin
-// Video call
-val videoSettings = CometChatCalls.SessionSettingsBuilder()
-    .setSessionType(SessionType.VIDEO)
-    .setLayout(LayoutType.TILE)
-    .setAudioMode(AudioMode.SPEAKER)
-    .startVideoPaused(false)
-    .build()
-
-// Voice call
-val voiceSettings = CometChatCalls.SessionSettingsBuilder()
-    .setSessionType(SessionType.VOICE)
-    .setLayout(LayoutType.SPOTLIGHT)
-    .setAudioMode(AudioMode.EARPIECE)
-    .startVideoPaused(true)
-    .build()
-```
-
-## Gotchas
-
-- The container **must** be a `RelativeLayout`, not `FrameLayout`
-- All participants must use the **same session ID** to join the same call
-- `SessionType` values are `VIDEO` and `VOICE` (not "AUDIO")
-- Call `joinSession` only after SDK is initialized and user is logged in
-- The `CallSession` returned in `onSuccess` is used to register all event listeners
-
-## Sample App Reference
-
-- `CallActivity.kt` — `joinSession()` method with voice/video branching
-- `Repository.kt` — `loginCallsUser()` for authentication before joining