@cometchat/skills 4.4.2 → 5.0.1

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

@@ -1,274 +0,0 @@
-# Call session — joinSession with no ringing (Android V5 / Views)
-
-Server-generated sessionId, both parties enter it. Customer-validated against `calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`.
-
-**Read first:** `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server-side authorization). Then come back here for the Android shape.
-
----
-
-## Hard rules (Android-specific overrides on top of the cross-platform rules)
-
-1. **`CometChatCalls.joinSession(sessionId, sessionSettings, container, CallbackListener<CallSession>)`** takes the sessionId DIRECTLY — token generation happens internally. No separate `generateToken` call required. Matches the upstream sample.
-2. **`CometChatCalls.SessionSettingsBuilder()` is the canonical settings shape** (nested class on `CometChatCalls`). Chained `.setTitle().startVideoPaused(false).startAudioMuted(false).build()`. NOT `SessionSettings(sessionType:, layout:)` — that constructor does not exist on Android.
-3. **`SessionStatusListener` + `ButtonClickListener` are abstract classes registered on the `CallSession` instance** returned in `onSuccess`. NOT `CometChatCalls.addEventListener(CallEvent.SESSION_LEFT)` — that does not exist.
-4. **`CometChatOngoingCallService.launch(this)` + `.abort(this)`** manage the platform foreground service. Call `launch()` in `onSessionJoined`; call `abort()` in EVERY termination path (`onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut`, `onDestroy`, `endCall`). Service notification persists otherwise.
-5. **For standalone session-only integrations, the Chat SDK is OPTIONAL.** The upstream Android sample only depends on `com.cometchat.calls-sdk-android`. Keep `CometChat.init` / `CometChat.login` only for additive (chat + calls) integrations.
-6. **Runtime permission request** for `CAMERA` + `RECORD_AUDIO` (Android 6.0+). The manifest entries are necessary but not sufficient on modern Android.
-
----
-
-## CallActivity (canonical XML/Views shape)
-
-```kotlin
-package com.example.calls
-
-import android.os.Bundle
-import android.util.Log
-import android.widget.RelativeLayout
-import android.widget.Toast
-import androidx.activity.OnBackPressedCallback
-import androidx.appcompat.app.AppCompatActivity
-import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.core.CometChatCalls
-import com.cometchat.calls.exceptions.CometChatException
-import com.cometchat.calls.listeners.ButtonClickListener
-import com.cometchat.calls.listeners.SessionStatusListener
-import com.cometchat.calls.services.CometChatOngoingCallService
-
-class CallActivity : AppCompatActivity() {
-
-  companion object {
-    private const val TAG = "CallActivity"
-    const val EXTRA_SESSION_ID = "session_id"
-  }
-
-  private lateinit var callContainer: RelativeLayout
-  private lateinit var sessionId: String
-
-  override fun onCreate(savedInstanceState: Bundle?) {
-    super.onCreate(savedInstanceState)
-    setContentView(R.layout.activity_call)
-
-    sessionId = intent.getStringExtra(EXTRA_SESSION_ID) ?: run {
-      Toast.makeText(this, "Invalid session ID", Toast.LENGTH_SHORT).show()
-      finish()
-      return
-    }
-
-    callContainer = findViewById(R.id.call_container)
-
-    onBackPressedDispatcher.addCallback(this, object : OnBackPressedCallback(true) {
-      override fun handleOnBackPressed() = endCall()
-    })
-
-    joinSession()
-  }
-
-  private fun joinSession() {
-    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
-      .setTitle("CometChat Meeting")
-      .startVideoPaused(false)
-      .startAudioMuted(false)
-      .build()
-
-    CometChatCalls.joinSession(
-      sessionId,
-      sessionSettings,
-      callContainer,
-      object : CometChatCalls.CallbackListener<CallSession>() {
-        override fun onSuccess(callSession: CallSession) {
-          Log.d(TAG, "Joined session: $sessionId")
-          setupCallListeners(callSession)
-        }
-
-        override fun onError(e: CometChatException) {
-          Log.e(TAG, "Failed to join session: ${e.message}")
-          runOnUiThread {
-            Toast.makeText(this@CallActivity, "Failed to join: ${e.message}", Toast.LENGTH_LONG).show()
-            finish()
-          }
-        }
-      }
-    )
-  }
-
-  private fun setupCallListeners(callSession: CallSession) {
-    callSession.addSessionStatusListener(this, object : SessionStatusListener() {
-      override fun onSessionJoined() {
-        CometChatOngoingCallService.launch(this@CallActivity)
-      }
-
-      // All termination events funnel through ONE guarded handleTermination().
-      // The v5 Calls SDK fires onSessionLeft + onConnectionClosed in sequence
-      // on every hangup. Activity.finish() is idempotent (safe to call multiple
-      // times) but abort() isn't — multiple abort calls log warnings and waste
-      // foreground-service teardown work.
-      override fun onSessionLeft() = handleTermination()
-      override fun onConnectionClosed() = handleTermination()
-      override fun onSessionTimedOut() = handleTermination()
-
-      override fun onConnectionLost() {
-        runOnUiThread {
-          Toast.makeText(this@CallActivity, "Connection lost", Toast.LENGTH_SHORT).show()
-        }
-      }
-
-      override fun onConnectionRestored() {
-        runOnUiThread {
-          Toast.makeText(this@CallActivity, "Connection restored", Toast.LENGTH_SHORT).show()
-        }
-      }
-    })
-
-    callSession.addButtonClickListener(this, object : ButtonClickListener() {
-      override fun onLeaveSessionButtonClicked() = endCall()
-    })
-  }
-
-  private var isTerminating = false
-
-  private fun handleTermination() {
-    if (isTerminating) return
-    isTerminating = true
-    runOnUiThread {
-      CometChatOngoingCallService.abort(this)
-      if (!isFinishing) finish()
-    }
-  }
-
-  private fun endCall() {
-    val callSession = CallSession.getInstance()
-    if (callSession.isSessionActive) callSession.leaveSession()
-    handleTermination()
-  }
-
-  override fun onDestroy() {
-    super.onDestroy()
-    CometChatOngoingCallService.abort(this)
-  }
-}
-```
-
-XML (`res/layout/activity_call.xml`):
-
-```xml
-<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:id="@+id/call_container"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent"
-    android:background="@android:color/black" />
-```
-
-**Why this shape:**
-
-- **Single-call `joinSession(sessionId, settings, container, callback)`** — token generation is internal. Customers don't manage tokens; the SDK does.
-- **`CometChatCalls.SessionSettingsBuilder()` (nested class)** — the outer namespacing matters; raw `SessionSettingsBuilder()` won't resolve.
-- **Listener-on-`CallSession`-instance pattern** — register against the `CallSession` from `onSuccess`, NOT against the global `CometChatCalls` singleton. Each session has its own listener registry.
-- **`onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut` ALL terminate the activity.** All three are real termination paths.
-- **`CometChatOngoingCallService.launch/abort`** — required for Android 14+ foreground-service compliance with `FOREGROUND_SERVICE_MICROPHONE`. Skipping `abort()` leaves the persistent notification.
-
----
-
-## Manifest requirements
-
-```xml
-<uses-permission android:name="android.permission.INTERNET" />
-<uses-permission android:name="android.permission.CAMERA" />
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
-<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
-<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
-<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-
-<application>
-  <activity android:name=".CallActivity" />
-  <service
-    android:name="com.cometchat.calls.services.CometChatOngoingCallService"
-    android:foregroundServiceType="microphone|camera"
-    android:exported="false" />
-</application>
-```
-
----
-
-## Runtime permissions (Kotlin)
-
-```kotlin
-val permLauncher = registerForActivityResult(
-  ActivityResultContracts.RequestMultiplePermissions()
-) { perms ->
-  val granted = perms[Manifest.permission.CAMERA] == true &&
-                perms[Manifest.permission.RECORD_AUDIO] == true
-  if (granted) {
-    // proceed to call
-  } else {
-    // show explanation + deep-link to app settings
-  }
-}
-
-permLauncher.launch(arrayOf(
-  Manifest.permission.CAMERA,
-  Manifest.permission.RECORD_AUDIO,
-  Manifest.permission.POST_NOTIFICATIONS,  // Android 13+
-))
-```
-
----
-
-## Deep-link routing (App Links)
-
-```xml
-<activity android:name=".CallActivity">
-  <intent-filter android:autoVerify="true">
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="https" android:host="yourapp.com" android:pathPrefix="/meet/" />
-  </intent-filter>
-</activity>
-```
-
-`MainActivity.onCreate` / `onNewIntent` routes to `CallActivity` extracting the sessionId from `intent.data.lastPathSegment`.
-
-See `cometchat-android-v5-calls/references/share-invite.md` for full deep-link config.
-
----
-
-## Anti-patterns
-
-1. **`CometChatCalls.generateToken(sessionId)` then `joinSession(callToken, ...)` two-step.** The Android API takes sessionId directly via `joinSession(sessionId, settings, container, callback)`. The two-step exists for advanced cases (custom auth tokens) but the canonical pattern is single-call.
-2. **`SessionSettings(sessionType:, layout:)` data-class constructor.** Doesn't exist on Android. Use `CometChatCalls.SessionSettingsBuilder().build()`.
-3. **`CometChatCalls.addEventListener(CallEvent.SESSION_LEFT)`.** Doesn't exist on Android. Register `SessionStatusListener()` on the `CallSession` instance from `onSuccess`.
-4. **Skipping `CometChatOngoingCallService.abort()` in `onDestroy` / `onConnectionClosed` / `onSessionTimedOut`.** Foreground-service notification persists; user sees "Ongoing call" with no way to clear.
-5. **`addSessionStatusListener` without the `lifecycleOwner` (this) argument.** The two-arg form `(lifecycleOwner, listener)` ties listener cleanup to the activity's lifecycle — required to avoid leaks.
-6. **Calling `leaveSession()` without checking `callSession.isSessionActive`.** Throws on double-leave; can happen if back button + onSessionLeft fire concurrently.
-7. **Initializing Chat SDK for a session-only integration.** Wastes time and adds two extra failure modes. Drop `CometChat.init` / `CometChat.login` entirely for standalone session apps.
-
----
-
-## Verification checklist
-
-- [ ] `CometChatCalls.joinSession(sessionId, settings, container, CallbackListener)` — single-call shape
-- [ ] Settings built via `CometChatCalls.SessionSettingsBuilder()`, not constructor
-- [ ] `SessionStatusListener()` registered on the `CallSession` from `onSuccess` (with lifecycle owner)
-- [ ] `ButtonClickListener()` registered for the leave button
-- [ ] `CometChatOngoingCallService.launch(this)` in `onSessionJoined`
-- [ ] `CometChatOngoingCallService.abort(this)` in EVERY termination path
-- [ ] Manifest has `FOREGROUND_SERVICE_MICROPHONE` + `FOREGROUND_SERVICE_CAMERA` (Android 14+)
-- [ ] `<service android:name="com.cometchat.calls.services.CometChatOngoingCallService" android:foregroundServiceType="microphone|camera" />` in manifest
-- [ ] Runtime permission request for `CAMERA`, `RECORD_AUDIO`, `POST_NOTIFICATIONS`
-- [ ] App Links intent-filter for `/meet/*`
-- [ ] **Standalone session-only:** no `com.cometchat:chat-sdk-android` dependency — Calls SDK alone
-- [ ] **Additive (chat + calls):** dual-SDK contract preserved
-- [ ] Real-device smoke: rotation doesn't double-join, leave clears the foreground notification
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/call-session.md` — cross-platform architecture
-- `cometchat-android-v5-calls/SKILL.md` — Android V5 architecture
-- `cometchat-android-v5-calls/references/share-invite.md` — App Links config
-- Upstream Android sample — `calls-sdk-android-5/samples/sample-app/src/main/kotlin/com/cometchat/samplecalls/ui/activity/CallActivity.kt`
-- Canonical docs: https://www.cometchat.com/docs/calls/android/join-session

package/skills/cometchat-android-v5-calls/references/custom-ui.md

@@ -1,150 +0,0 @@
----
-name: custom-ui
-description: Build custom call UI — custom control panel, custom participant list, layout customization. Use when hiding default controls and building your own call interface. Triggers on "custom control panel", "custom participant list", "custom UI", "hideControlPanel", "custom call interface".
-inclusion: manual
----
-
-# CometChat Calls SDK v5 — Custom UI
-
-## Overview
-
-Build fully custom call interfaces by hiding the default SDK controls and implementing your own using `CallSession` actions and event listeners.
-
-## Key Imports
-
-```kotlin
-import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.core.CometChatCalls
-import com.cometchat.calls.listeners.MediaEventsListener
-import com.cometchat.calls.listeners.SessionStatusListener
-import com.cometchat.calls.listeners.ParticipantEventListener
-import com.cometchat.calls.model.*
-```
-
-## Implementation
-
-### 1. Hide Default Controls
-
-```kotlin
-val sessionSettings = CometChatCalls.SessionSettingsBuilder()
-    .hideControlPanel(true)          // hide entire bottom bar
-    .hideHeaderPanel(true)           // hide top header
-    // Or hide individual buttons:
-    // .hideToggleAudioButton(true)
-    // .hideToggleVideoButton(true)
-    // .hideParticipantListButton(true)
-    .build()
-```
-
-### 2. Custom Control Panel
-
-Create your own buttons and wire them to `CallSession` actions:
-
-```kotlin
-val callSession = CallSession.getInstance()
-var isAudioMuted = false
-var isVideoPaused = false
-
-btnMute.setOnClickListener {
-    if (isAudioMuted) callSession.unmuteAudio() else callSession.muteAudio()
-}
-btnVideo.setOnClickListener {
-    if (isVideoPaused) callSession.resumeVideo() else callSession.pauseVideo()
-}
-btnSwitchCamera.setOnClickListener { callSession.switchCamera() }
-btnEndCall.setOnClickListener {
-    callSession.leaveSession()
-    finish()
-}
-```
-
-### 3. Sync UI with Media Events
-
-```kotlin
-callSession.addMediaEventsListener(this, object : MediaEventsListener() {
-    override fun onAudioMuted() {
-        runOnUiThread { isAudioMuted = true; btnMute.setImageResource(R.drawable.ic_mic_off) }
-    }
-    override fun onAudioUnMuted() {
-        runOnUiThread { isAudioMuted = false; btnMute.setImageResource(R.drawable.ic_mic_on) }
-    }
-    override fun onVideoPaused() {
-        runOnUiThread { isVideoPaused = true; btnVideo.setImageResource(R.drawable.ic_video_off) }
-    }
-    override fun onVideoResumed() {
-        runOnUiThread { isVideoPaused = false; btnVideo.setImageResource(R.drawable.ic_video_on) }
-    }
-    // ... other overrides
-})
-```
-
-### 4. Custom Participant List
-
-Hide default and build with RecyclerView:
-
-```kotlin
-// Hide default
-.hideParticipantListButton(true)
-
-// Listen for participant updates
-callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
-    override fun onParticipantListChanged(participants: List<Participant>) {
-        runOnUiThread { adapter.updateParticipants(participants) }
-    }
-    // ... other overrides
-})
-
-// Participant actions from custom UI
-adapter.onMuteClick = { participant -> callSession.muteParticipant(participant.uid) }
-adapter.onPauseVideoClick = { participant -> callSession.pauseParticipantVideo(participant.uid) }
-adapter.onPinClick = { participant ->
-    if (participant.isPinned) callSession.unpinParticipant()
-    else callSession.pinParticipant(participant.uid)  // per official docs (calls/android/participant-management)
-}
-```
-
-### 5. Layout Control
-
-```kotlin
-// Change layout programmatically
-callSession.setLayout(LayoutType.TILE)
-callSession.setLayout(LayoutType.SPOTLIGHT)
-
-// Listen for layout changes
-callSession.addLayoutListener(this, object : LayoutListener() {
-    override fun onCallLayoutChanged(layoutType: LayoutType) { /* update UI */ }
-    override fun onParticipantListVisible() {}
-    override fun onParticipantListHidden() {}
-    override fun onPictureInPictureLayoutEnabled() {}
-    override fun onPictureInPictureLayoutDisabled() {}
-})
-```
-
-### Available CallSession Actions
-
-| Action | Method |
-|--------|--------|
-| Mute/unmute audio | `muteAudio()`, `unmuteAudio()` |
-| Pause/resume video | `pauseVideo()`, `resumeVideo()` |
-| Switch camera | `switchCamera()` |
-| Change audio output | `setAudioMode(AudioMode)` |
-| Change layout | `setLayout(LayoutType)` |
-| Start/stop recording | `startRecording()`, `stopRecording()` |
-| Pin/unpin participant | `pinParticipant(uid)`, `unpinParticipant()` |
-| Mute participant | `muteParticipant(uid)` |
-| Pause participant video | `pauseParticipantVideo(uid)` |
-| Leave session | `leaveSession()` |
-| Enable/disable PiP | `enablePictureInPictureLayout()`, `disablePictureInPictureLayout()` |
-| Set chat badge count | `setChatButtonUnreadCount(count)` |
-
-## Gotchas
-
-- Always use `MediaEventsListener` to sync your custom UI with actual state
-- `runOnUiThread {}` is required for UI updates from listener callbacks
-- `hideControlPanel(true)` hides the entire bottom bar — individual hide methods are ignored
-- The call view container still renders video tiles even with controls hidden
-- Use `SessionStatusListener` to handle session end and navigate away
-
-## Sample App Reference
-
-- `CallActivity.kt` — Default UI with `SessionStatusListener` and `ButtonClickListener`

package/skills/cometchat-android-v5-calls/references/event-listeners.md

@@ -1,123 +0,0 @@
----
-name: event-listeners
-description: Register all five call event listeners — SessionStatusListener, ParticipantEventListener, MediaEventsListener, ButtonClickListener, LayoutListener. Use when handling call events, session status, participant changes, media state, button clicks, or layout changes. Triggers on "event listener", "session listener", "participant listener", "media listener", "button click", "layout listener".
-inclusion: manual
----
-
-# CometChat Calls SDK v5 — Event Listeners
-
-## Overview
-
-Five lifecycle-aware listeners monitor call events. All are registered on `CallSession.getInstance()` and auto-removed when the `LifecycleOwner` (Activity/Fragment) is destroyed.
-
-## Key Imports
-
-```kotlin
-import com.cometchat.calls.core.CallSession
-import com.cometchat.calls.listeners.SessionStatusListener
-import com.cometchat.calls.listeners.ParticipantEventListener
-import com.cometchat.calls.listeners.MediaEventsListener
-import com.cometchat.calls.listeners.ButtonClickListener
-import com.cometchat.calls.listeners.LayoutListener
-import com.cometchat.calls.model.Participant
-import com.cometchat.calls.model.AudioMode
-import com.cometchat.calls.model.CameraFacing
-import com.cometchat.calls.model.LayoutType
-```
-
-## Implementation
-
-### 1. SessionStatusListener
-
-```kotlin
-val callSession = CallSession.getInstance()
-
-callSession.addSessionStatusListener(this, object : SessionStatusListener() {
-    override fun onSessionJoined() { /* connected */ }
-    override fun onSessionLeft() { finish() }
-    override fun onSessionTimedOut() { finish() }
-    override fun onConnectionLost() { /* show reconnecting UI */ }
-    override fun onConnectionRestored() { /* hide reconnecting UI */ }
-    override fun onConnectionClosed() { finish() }
-})
-```
-
-### 2. ParticipantEventListener
-
-```kotlin
-callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
-    override fun onParticipantJoined(participant: Participant) {}
-    override fun onParticipantLeft(participant: Participant) {}
-    override fun onParticipantListChanged(participants: List<Participant>) {}
-    override fun onParticipantAudioMuted(participant: Participant) {}
-    override fun onParticipantAudioUnmuted(participant: Participant) {}
-    override fun onParticipantVideoPaused(participant: Participant) {}
-    override fun onParticipantVideoResumed(participant: Participant) {}
-    override fun onParticipantHandRaised(participant: Participant) {}
-    override fun onParticipantHandLowered(participant: Participant) {}
-    override fun onParticipantStartedScreenShare(participant: Participant) {}
-    override fun onParticipantStoppedScreenShare(participant: Participant) {}
-    override fun onParticipantStartedRecording(participant: Participant) {}
-    override fun onParticipantStoppedRecording(participant: Participant) {}
-    override fun onDominantSpeakerChanged(participant: Participant) {}
-})
-```
-
-### 3. MediaEventsListener
-
-```kotlin
-callSession.addMediaEventsListener(this, object : MediaEventsListener() {
-    override fun onAudioMuted() {}
-    override fun onAudioUnMuted() {}
-    override fun onVideoPaused() {}
-    override fun onVideoResumed() {}
-    override fun onRecordingStarted() {}
-    override fun onRecordingStopped() {}
-    override fun onAudioModeChanged(audioMode: AudioMode) {}
-    override fun onCameraFacingChanged(facing: CameraFacing) {}
-})
-// Screen-share is observed on ParticipantEventListener (onParticipantStartedScreenShare /
-// onParticipantStoppedScreenShare above) — NOT MediaEventsListener.
-```
-
-### 4. ButtonClickListener
-
-```kotlin
-callSession.addButtonClickListener(this, object : ButtonClickListener() {
-    override fun onLeaveSessionButtonClicked() {}
-    override fun onToggleAudioButtonClicked() {}
-    override fun onToggleVideoButtonClicked() {}
-    override fun onSwitchCameraButtonClicked() {}
-    override fun onRaiseHandButtonClicked() {}
-    override fun onShareInviteButtonClicked() {}
-    override fun onChangeLayoutButtonClicked() {}
-    override fun onParticipantListButtonClicked() {}
-    override fun onChatButtonClicked() {}
-    override fun onRecordingToggleButtonClicked() {}
-})
-```
-
-### 5. LayoutListener
-
-```kotlin
-callSession.addLayoutListener(this, object : LayoutListener() {
-    override fun onCallLayoutChanged(layoutType: LayoutType) {}
-    override fun onParticipantListVisible() {}
-    override fun onParticipantListHidden() {}
-    override fun onPictureInPictureLayoutEnabled() {}
-    override fun onPictureInPictureLayoutDisabled() {}
-})
-```
-
-## Gotchas
-
-- All listeners are **lifecycle-aware** — no manual removal needed
-- Pass `this` (Activity/Fragment) as the first argument for lifecycle binding
-- Register listeners **after** `joinSession()` succeeds (in the `onSuccess` callback)
-- Button click events fire **before** the SDK's default action
-- `Participant` object has: `uid`, `name`, `avatar`, `isAudioMuted`, `isVideoPaused`, `isPresenting`, `isPinned`, `raisedHandTimestamp`
-- Use `runOnUiThread {}` for UI updates inside listener callbacks
-
-## Sample App Reference
-
-- `CallActivity.kt` — `setupCallListeners()` registers `SessionStatusListener` and `ButtonClickListener`