@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-android-v5-calls/references/audio-controls.md

@@ -0,0 +1,91 @@
+---
+name: audio-controls
+description: Control audio during calls — mute/unmute microphone, switch audio output device (speaker, earpiece, bluetooth). Use when implementing audio toggle, audio mode switching, or custom mute buttons. Triggers on "mute audio", "unmute", "audio mode", "speaker", "earpiece", "bluetooth audio".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Audio Controls
+
+## Overview
+
+Programmatically control the local microphone (mute/unmute) and audio output device (speaker, earpiece, Bluetooth, headphones) during an active call.
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.model.AudioMode
+import com.cometchat.calls.listeners.MediaEventsListener
+```
+
+## Implementation
+
+### Mute / Unmute
+
+```kotlin
+val callSession = CallSession.getInstance()
+
+callSession.muteAudio()    // mute microphone
+callSession.unMuteAudio()  // unmute microphone
+```
+
+### Switch Audio Output
+
+```kotlin
+callSession.setAudioMode(AudioMode.SPEAKER)     // loudspeaker
+callSession.setAudioMode(AudioMode.EARPIECE)     // phone earpiece
+callSession.setAudioMode(AudioMode.BLUETOOTH)    // connected Bluetooth device
+callSession.setAudioMode(AudioMode.HEADPHONES)   // wired headphones
+```
+
+### Listen for Audio Events
+
+```kotlin
+callSession.addMediaEventsListener(this, object : MediaEventsListener() {
+    override fun onAudioMuted() {
+        // Update mute button to "muted" state
+    }
+    override fun onAudioUnMuted() {
+        // Update mute button to "unmuted" state
+    }
+    override fun onAudioModeChanged(audioMode: AudioMode) {
+        when (audioMode) {
+            AudioMode.SPEAKER -> { /* update icon */ }
+            AudioMode.EARPIECE -> { /* update icon */ }
+            AudioMode.BLUETOOTH -> { /* update icon */ }
+            AudioMode.HEADPHONES -> { /* update icon */ }
+        }
+    }
+    // ... other required overrides
+    override fun onVideoPaused() {}
+    override fun onVideoResumed() {}
+    override fun onRecordingStarted() {}
+    override fun onRecordingStopped() {}
+    override fun onScreenShareStarted() {}
+    override fun onScreenShareStopped() {}
+    override fun onCameraFacingChanged(facing: CameraFacing) {}
+})
+```
+
+### Initial Audio Settings (Pre-Session)
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .startAudioMuted(true)              // join muted
+    .setAudioMode(AudioMode.SPEAKER)    // initial output device
+    .hideToggleAudioButton(false)       // show mute button
+    .hideAudioModeButton(false)         // show audio mode button
+    .build()
+```
+
+## Gotchas
+
+- `muteAudio()` / `unMuteAudio()` only work during an active session
+- Audio mode changes trigger `onAudioModeChanged()` on `MediaEventsListener`
+- `AudioMode` enum: `SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES`
+- For voice calls, default to `AudioMode.EARPIECE`; for video calls, default to `AudioMode.SPEAKER`
+- Bluetooth audio mode only works when a Bluetooth device is connected
+
+## Sample App Reference
+
+- `CallActivity.kt` — Sets `AudioMode.EARPIECE` for voice calls, `AudioMode.SPEAKER` for video calls

package/skills/cometchat-android-v5-calls/references/background-handling.md

@@ -0,0 +1,168 @@
+---
+name: background-handling
+description: Keep calls alive in background using CometChatOngoingCallService foreground service. Use when handling home button press during calls, ongoing call notifications, or preventing call termination. Triggers on "background handling", "foreground service", "ongoing call", "CometChatOngoingCallService", "keep call alive".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Background Handling
+
+## Overview
+
+`CometChatOngoingCallService` is a foreground service that keeps calls alive when users press HOME or switch apps. Shows an ongoing notification with tap-to-return and hangup actions.
+
+## Prerequisites
+
+- Active call session
+- Foreground service permissions in manifest
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.services.CometChatOngoingCallService
+import com.cometchat.calls.utils.OngoingNotification
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.SessionStatusListener
+import com.cometchat.calls.listeners.ButtonClickListener
+```
+
+## Implementation
+
+### 1. Manifest Permissions
+
+```xml
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+```
+
+### 2. Start/Stop Service
+
+```kotlin
+callSession.addSessionStatusListener(this, object : SessionStatusListener() {
+    override fun onSessionJoined() {
+        CometChatOngoingCallService.launch(this@CallActivity)
+    }
+    override fun onSessionLeft() {
+        CometChatOngoingCallService.abort(this@CallActivity)
+        finish()
+    }
+    override fun onConnectionClosed() {
+        CometChatOngoingCallService.abort(this@CallActivity)
+        finish()
+    }
+    override fun onSessionTimedOut() {
+        CometChatOngoingCallService.abort(this@CallActivity)
+        finish()
+    }
+    override fun onConnectionLost() {}
+    override fun onConnectionRestored() {}
+})
+```
+
+### 3. Handle Leave Button
+
+```kotlin
+callSession.addButtonClickListener(this, object : ButtonClickListener() {
+    override fun onLeaveSessionButtonClicked() {
+        endCall()
+    }
+})
+```
+
+### 4. Handle Remote Call End
+
+Register a `CometChat.CallListener` to detect when the remote party ends the call, then clean up the foreground service:
+
+```kotlin
+CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener() {
+    override fun onCallEndedMessageReceived(call: Call?) {
+        val session = CallSession.getInstance()
+        if (session.isSessionActive) {
+            session.leaveSession()
+        }
+        CometChatOngoingCallService.abort(this@CallActivity)
+        runOnUiThread { finish() }
+    }
+    override fun onIncomingCallReceived(call: Call?) {}
+    override fun onOutgoingCallAccepted(call: Call?) {}
+    override fun onOutgoingCallRejected(call: Call?) {}
+    override fun onIncomingCallCancelled(call: Call?) {}
+})
+```
+
+### 5. Always Stop in onDestroy
+
+```kotlin
+override fun onDestroy() {
+    super.onDestroy()
+    CometChat.removeCallListener(LISTENER_ID)
+    CometChatOngoingCallService.abort(this)
+}
+```
+
+### 6. Custom Notification (Optional)
+
+```kotlin
+private fun buildCustomNotification(): Notification {
+    val channelId = "CometChat_Call_Ongoing_Conference"  // must use this ID
+    val intent = Intent(this, CallActivity::class.java).apply {
+        flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
+    }
+    val pendingIntent = PendingIntent.getActivity(
+        this, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+    )
+    return NotificationCompat.Builder(this, channelId)
+        .setSmallIcon(R.drawable.ic_call)
+        .setContentTitle("Ongoing Call")
+        .setContentText("Tap to return to your call")
+        .setPriority(NotificationCompat.PRIORITY_HIGH)
+        .setContentIntent(pendingIntent)
+        .setOngoing(true)
+        .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+        .build()
+}
+
+// Set before launching service
+OngoingNotification.buildOngoingConferenceNotification(buildCustomNotification())
+CometChatOngoingCallService.launch(this)
+```
+
+### 7. VoIP Integration — Additional Cleanup (Optional)
+
+When using background handling with VoIP calling (ConnectionService + TelecomManager), also disconnect the `CallConnection` and cancel any VoIP notifications on every terminal state:
+
+```kotlin
+// In each terminal callback (onSessionLeft, onSessionTimedOut, onConnectionClosed, onCallEndedMessageReceived):
+CometChatOngoingCallService.abort(this@CallActivity)
+CallConnectionHolder.endCall()
+CallNotificationManager.cancelNotification(this@CallActivity)
+finish()
+```
+
+See the `sample-app-voip` CallActivity for the full VoIP-integrated pattern.
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `CometChatOngoingCallService.launch(context)` | Start foreground service |
+| `CometChatOngoingCallService.abort(context)` | Stop foreground service |
+| `OngoingNotification.buildOngoingConferenceNotification(notification)` | Set custom notification (call before `launch()`) |
+
+## Gotchas
+
+- The notification channel ID **must** be `"CometChat_Call_Ongoing_Conference"`
+- Always call `abort()` in `onDestroy()` to prevent leaked services
+- Always remove `CometChat.CallListener` in `onDestroy()` to prevent leaks
+- This is for keeping **active** calls alive — for receiving calls when app is killed, use VoIP Calling
+- Call `launch()` only after `onSessionJoined()` — not before joining
+- Custom notification must be set **before** calling `launch()`
+- When using VoIP (ConnectionService), also call `CallConnectionHolder.endCall()` in every terminal state to properly disconnect the Telecom connection
+
+## Sample App Reference
+
+- `sample-app-ringing` — `CallActivity.kt` — basic foreground service pattern with `launch()` in `onSessionJoined()`, `abort()` in `onSessionLeft()` and `onDestroy()`
+- `sample-app-voip` — `CallActivity.kt` — full VoIP-integrated pattern with foreground service + CallConnection cleanup + notification cancellation on every terminal state

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

@@ -0,0 +1,123 @@
+# Call layouts on Android V5 (Views)
+
+Same three layouts (TILE/SIDEBAR/SPOTLIGHT). Android V5 uses Java/Kotlin builders + `MaterialButtonToggleGroup` for the switcher (Material Components for Android).
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/android/call-layouts
+**Read first:** `cometchat-react-calls/references/call-layouts.md` — layout matrix + when to lock.
+
+---
+
+## SDK API
+
+```kotlin
+import com.cometchat.calls.constants.CometChatCallsConstants
+import com.cometchat.calls.core.CallSettingsBuilder
+import com.cometchat.calls.core.CometChatCalls
+
+val settings = CallSettingsBuilder(activity)
+  .setSessionType(CometChatCallsConstants.SESSION_TYPE_VIDEO)
+  .setLayout(CometChatCallsConstants.LAYOUT_TILE)        // _TILE | _SIDEBAR | _SPOTLIGHT
+  .setHideChangeLayoutButton(false)
+  .build()
+
+// Mid-call switch
+CometChatCalls.setLayout(CometChatCallsConstants.LAYOUT_SPOTLIGHT)
+
+// Listen
+val callsEventListener = object : CometChatCallsEventsListener {
+  override fun onCallLayoutChanged(layout: String) {
+    activity.runOnUiThread {
+      // Update segmented button state
+    }
+  }
+}
+```
+
+---
+
+## XML — MaterialButtonToggleGroup
+
+```xml
+<com.google.android.material.button.MaterialButtonToggleGroup
+    android:id="@+id/layoutToggle"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    app:singleSelection="true"
+    app:selectionRequired="true"
+    android:contentDescription="@string/call_layout">
+
+  <com.google.android.material.button.MaterialButton
+      android:id="@+id/layoutTile"
+      style="@style/Widget.Material3.Button.OutlinedButton"
+      android:text="@string/layout_tile" />
+
+  <com.google.android.material.button.MaterialButton
+      android:id="@+id/layoutSidebar"
+      style="@style/Widget.Material3.Button.OutlinedButton"
+      android:text="@string/layout_sidebar" />
+
+  <com.google.android.material.button.MaterialButton
+      android:id="@+id/layoutSpotlight"
+      style="@style/Widget.Material3.Button.OutlinedButton"
+      android:text="@string/layout_spotlight" />
+</com.google.android.material.button.MaterialButtonToggleGroup>
+```
+
+---
+
+## Wire-up in Activity
+
+```kotlin
+binding.layoutToggle.addOnButtonCheckedListener { _, checkedId, isChecked ->
+  if (!isChecked) return@addOnButtonCheckedListener
+
+  val layout = when (checkedId) {
+    R.id.layoutTile -> CometChatCallsConstants.LAYOUT_TILE
+    R.id.layoutSidebar -> CometChatCallsConstants.LAYOUT_SIDEBAR
+    R.id.layoutSpotlight -> CometChatCallsConstants.LAYOUT_SPOTLIGHT
+    else -> return@addOnButtonCheckedListener
+  }
+  CometChatCalls.setLayout(layout)
+}
+
+// Sync from kit's switcher
+override fun onCallLayoutChanged(layout: String) {
+  runOnUiThread {
+    val id = when (layout) {
+      CometChatCallsConstants.LAYOUT_TILE -> R.id.layoutTile
+      CometChatCallsConstants.LAYOUT_SIDEBAR -> R.id.layoutSidebar
+      CometChatCallsConstants.LAYOUT_SPOTLIGHT -> R.id.layoutSpotlight
+      else -> return@runOnUiThread
+    }
+    binding.layoutToggle.check(id)
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Android-specific:
+
+1. **`Spinner` instead of `MaterialButtonToggleGroup`.** Spinner hides options; toggle group is the radio-group native pattern in Material.
+2. **`onCheckedChange` without `isChecked` guard.** Fires twice (once for unchecked, once for checked) — spurious `setLayout` calls.
+3. **Forgetting `runOnUiThread` in the listener.** Crash on view updates from background thread.
+
+---
+
+## Verification checklist
+
+- [ ] Initial layout via `setLayout` on builder
+- [ ] `MaterialButtonToggleGroup` with `singleSelection="true"`
+- [ ] `addOnButtonCheckedListener` guards on `isChecked`
+- [ ] `onCallLayoutChanged` updates toggle group on UI thread
+- [ ] Real-device smoke: switcher cycles all 3, kit's switcher syncs custom UI
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/call-layouts.md` — sister
+- `cometchat-android-v5-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/android/call-layouts

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

@@ -0,0 +1,113 @@
+---
+name: call-logs
+description: Fetch call history using CallLogRequest with pagination and filters. Use when displaying call logs, filtering by type/status/recording, or accessing recordings. Triggers on "call logs", "call history", "CallLogRequest", "fetch recordings".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Call Logs
+
+## Overview
+
+Retrieve call history using `CallLogRequest` with pagination, filtering by type, status, direction, recordings, and specific users/groups.
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.model.CallLog
+import com.cometchat.calls.model.CallLogRequest
+import com.cometchat.calls.model.Recording
+import com.cometchat.calls.exceptions.CometChatException
+```
+
+## Implementation
+
+### Basic Fetch
+
+```kotlin
+val callLogRequest = CallLogRequest.CallLogRequestBuilder()
+    .setLimit(30)
+    .build()
+
+callLogRequest.fetchNext(object : CometChatCalls.CallbackListener<List<CallLog>>() {
+    override fun onSuccess(callLogs: List<CallLog>) {
+        for (log in callLogs) {
+            Log.d(TAG, "Session: ${log.sessionID}, Duration: ${log.totalDuration}, Status: ${log.status}")
+        }
+    }
+    override fun onError(e: CometChatException) {
+        Log.e(TAG, "Error: ${e.message}")
+    }
+})
+```
+
+### Filtered Queries
+
+```kotlin
+// Video calls only
+CallLogRequest.CallLogRequestBuilder().setSessionType("video").setLimit(20).build()
+
+// Calls with recordings
+CallLogRequest.CallLogRequestBuilder().setHasRecording(true).build()
+
+// Missed incoming calls
+CallLogRequest.CallLogRequestBuilder().setCallStatus("missed").setCallDirection("incoming").build()
+
+// Calls with a specific user
+CallLogRequest.CallLogRequestBuilder().setUid("user_id").build()
+
+// Meeting calls only
+CallLogRequest.CallLogRequestBuilder().setCallCategory("meet").build()
+```
+
+### Pagination
+
+```kotlin
+// Forward pagination
+callLogRequest.fetchNext(listener)
+
+// Backward pagination
+callLogRequest.fetchPrevious(listener)
+```
+
+### Access Recordings
+
+```kotlin
+for (callLog in callLogs) {
+    if (callLog.isHasRecording) {
+        callLog.recordings?.forEach { recording ->
+            Log.d(TAG, "URL: ${recording.recordingURL}")
+            Log.d(TAG, "Duration: ${recording.duration} seconds")
+        }
+    }
+}
+```
+
+### CallLog Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sessionID` | String | Session identifier |
+| `type` | String | `video` or `audio` |
+| `status` | String | `ended`, `missed`, `rejected`, `cancelled`, etc. |
+| `callCategory` | String | `call` or `meet` |
+| `totalDuration` | String | Human-readable duration |
+| `totalParticipants` | int | Participant count |
+| `hasRecording` | boolean | Whether recorded |
+| `recordings` | List\<Recording\> | Recording objects |
+| `initiator` | CallEntity | Who started the call |
+| `receiver` | CallEntity | Who received the call |
+
+## Gotchas
+
+- `CallLogRequest` is from the **Calls SDK**, not the Chat SDK
+- `setSessionType()` takes lowercase strings: `"video"` or `"audio"`
+- `setCallDirection()` takes `"incoming"` or `"outgoing"`
+- `setCallCategory()` takes `"call"` or `"meet"`
+- Create a new `CallLogRequest` to reset pagination
+- The sample app uses Chat SDK's `MessagesRequest` for call logs — the Calls SDK's `CallLogRequest` provides richer data
+
+## Sample App Reference
+
+- `Repository.kt` — `fetchCallLogs()` (uses Chat SDK approach)
+- For Calls SDK approach, use `CallLogRequest` as shown above