@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,101 @@
+---
+name: recording
+description: Record call sessions with start/stop, auto-start recording, and recording events. Use when implementing call recording, accessing recordings from call logs, or showing recording indicators. Triggers on "recording", "record call", "auto start recording", "recording events".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Recording
+
+## Overview
+
+Record call sessions server-side. Supports manual start/stop, auto-start via `SessionSettings`, and event listeners for recording state. Recordings are accessible via call logs or the CometChat Dashboard.
+
+## 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.ParticipantEventListener
+import com.cometchat.calls.model.CallLogRequest
+import com.cometchat.calls.model.Participant
+```
+
+## Implementation
+
+### Start/Stop Recording
+
+```kotlin
+val callSession = CallSession.getInstance()
+callSession.startRecording()
+callSession.stopRecording()
+```
+
+### Auto-Start Recording (SessionSettings)
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .enableAutoStartRecording(true)
+    .hideRecordingButton(false)  // show button (hidden by default)
+    .build()
+```
+
+### Listen for Recording Events (Local)
+
+```kotlin
+callSession.addMediaEventsListener(this, object : MediaEventsListener() {
+    override fun onRecordingStarted() { showRecordingIndicator() }
+    override fun onRecordingStopped() { hideRecordingIndicator() }
+    // ... other required overrides
+    override fun onAudioMuted() {}
+    override fun onAudioUnMuted() {}
+    override fun onVideoPaused() {}
+    override fun onVideoResumed() {}
+    override fun onScreenShareStarted() {}
+    override fun onScreenShareStopped() {}
+    override fun onAudioModeChanged(audioMode: AudioMode) {}
+    override fun onCameraFacingChanged(facing: CameraFacing) {}
+})
+```
+
+### Track Participant Recording
+
+```kotlin
+callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
+    override fun onParticipantStartedRecording(participant: Participant) {
+        Log.d(TAG, "${participant.name} started recording")
+    }
+    override fun onParticipantStoppedRecording(participant: Participant) {
+        Log.d(TAG, "${participant.name} stopped recording")
+    }
+    // ... other required overrides
+})
+```
+
+### Access Recordings from Call Logs
+
+```kotlin
+val request = CallLogRequest.CallLogRequestBuilder().setHasRecording(true).build()
+request.fetchNext(object : CometChatCalls.CallbackListener<List<CallLog>>() {
+    override fun onSuccess(callLogs: List<CallLog>) {
+        callLogs.forEach { log ->
+            log.recordings?.forEach { recording ->
+                Log.d(TAG, "URL: ${recording.recordingURL}, Duration: ${recording.duration}s")
+            }
+        }
+    }
+    override fun onError(e: CometChatException) {}
+})
+```
+
+## Gotchas
+
+- Recording must be **enabled** in your CometChat Dashboard
+- The recording button is **hidden by default** — use `.hideRecordingButton(false)` to show it
+- All participants are notified when recording starts
+- Recordings are stored server-side and available after the call ends
+- `Recording` object has: `rid`, `recordingURL`, `startTime`, `endTime`, `duration`
+
+## Sample App Reference
+
+- `CallActivity.kt` — Session settings configuration (recording button visibility)

package/skills/cometchat-android-v5-calls/references/ringing-integration.md

@@ -0,0 +1,152 @@
+---
+name: ringing-integration
+description: Implement ringing with dual SDK (Chat + Calls). Use when adding incoming/outgoing call screens, CometChat.initiateCall, accept/reject/cancel calls, or Call class from com.cometchat.chat.core. Triggers on "ringing", "incoming call", "outgoing call", "initiateCall", "acceptCall", "rejectCall".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Ringing Integration
+
+## Overview
+
+Implement call ringing using both CometChat Chat SDK (signaling) and Calls SDK (session). The Chat SDK handles initiating, accepting, rejecting, and cancelling calls. The Calls SDK manages the actual call session after acceptance.
+
+## Prerequisites
+
+- Both SDKs added to `build.gradle.kts`:
+  ```kotlin
+  implementation("com.cometchat:chat-sdk-android:4.0.+")
+  implementation("com.cometchat:calls-sdk-android:5.0.0-beta.2")
+  ```
+- Both SDKs initialized and user logged in to both
+
+## Key Imports
+
+```kotlin
+// Chat SDK — signaling
+import com.cometchat.chat.core.CometChat
+import com.cometchat.chat.core.Call                    // NOT com.cometchat.chat.models.Call
+import com.cometchat.chat.constants.CometChatConstants
+import com.cometchat.chat.exceptions.CometChatException as ChatException
+
+// Calls SDK — session
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.exceptions.CometChatException as CallsException
+```
+
+## Implementation
+
+### 1. Initiate a Call (Caller Side)
+
+```kotlin
+val call = Call(receiverUID, CometChatConstants.RECEIVER_TYPE_USER, CometChatConstants.CALL_TYPE_VIDEO)
+
+CometChat.initiateCall(call, object : CometChat.CallbackListener<Call>() {
+    override fun onSuccess(outgoingCall: Call) {
+        // Show outgoing call UI with outgoingCall.sessionId
+    }
+    override fun onError(e: ChatException) {
+        Log.e(TAG, "Initiate failed: ${e.message}")
+    }
+})
+```
+
+### 2. Listen for Incoming Calls (Global Listener)
+
+Register in `Application` class:
+
+```kotlin
+CometChat.addCallListener(LISTENER_ID, object : CometChat.CallListener() {
+    override fun onIncomingCallReceived(call: Call) {
+        // Show incoming call UI
+        // call.sessionId, call.sender?.name, call.type
+    }
+    override fun onOutgoingCallAccepted(call: Call) {
+        // Navigate to CallActivity with call.sessionId
+    }
+    override fun onOutgoingCallRejected(call: Call) {
+        // Dismiss outgoing call UI
+    }
+    override fun onIncomingCallCancelled(call: Call) {
+        // Dismiss incoming call UI
+    }
+    override fun onCallEndedMessageReceived(call: Call) {
+        // Handle call ended
+    }
+})
+```
+
+### 3. Accept a Call (Receiver Side)
+
+```kotlin
+CometChat.acceptCall(sessionId, object : CometChat.CallbackListener<Call>() {
+    override fun onSuccess(call: Call) {
+        // Navigate to CallActivity, join session with call.sessionId
+    }
+    override fun onError(e: ChatException) { /* handle */ }
+})
+```
+
+### 4. Reject a Call
+
+```kotlin
+CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_REJECTED,
+    object : CometChat.CallbackListener<Call>() {
+        override fun onSuccess(call: Call) { finish() }
+        override fun onError(e: ChatException) { finish() }
+    })
+```
+
+### 5. Cancel an Outgoing Call
+
+```kotlin
+CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_CANCELLED,
+    object : CometChat.CallbackListener<Call>() {
+        override fun onSuccess(call: Call) { finish() }
+        override fun onError(e: ChatException) { finish() }
+    })
+```
+
+### 6. End a Call (During Session)
+
+```kotlin
+// 1. Leave the Calls SDK session
+CallSession.getInstance().leaveSession()
+
+// 2. Notify via Chat SDK
+CometChat.endCall(sessionId, object : CometChat.CallbackListener<Call>() {
+    override fun onSuccess(call: Call) { finish() }
+    override fun onError(e: ChatException) { finish() }
+})
+```
+
+### 7. Handle Remote End
+
+```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)
+        finish()
+    }
+    // ... other callbacks
+})
+```
+
+## Gotchas
+
+- **Use `com.cometchat.chat.core.Call`** — NOT `com.cometchat.chat.models.Call`
+- Cancel uses `CometChat.rejectCall()` with `CALL_STATUS_CANCELLED` status
+- Always call `CometChat.endCall()` when ending — otherwise the other party won't know
+- Remove call listeners in `onDestroy()` to prevent memory leaks
+- Call type constants: `CALL_TYPE_VIDEO` and `CALL_TYPE_AUDIO` (from `CometChatConstants`)
+- Use alias imports to disambiguate exception classes between Chat and Calls SDKs
+
+## Sample App Reference
+
+- `RingingApplication.kt` — Global call listener registration
+- `OutgoingCallActivity.kt` — Cancel call, listen for accept/reject
+- `IncomingCallActivity.kt` — Accept/reject incoming call
+- `CallActivity.kt` — Join session after accept, end call flow
+- `Repository.kt` — `initiateCall()`, `acceptCall()`, `rejectCall()`, `cancelCall()`, `endCall()`

package/skills/cometchat-android-v5-calls/references/screen-sharing.md

@@ -0,0 +1,82 @@
+---
+name: screen-sharing
+description: Handle screen sharing in calls. Android can receive/view screen shares from web clients. Use when implementing screen share viewing, listening for screen share events, or checking presenter status. Triggers on "screen sharing", "screen share", "presenter", "share screen".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Screen Sharing
+
+## Overview
+
+The Android Calls SDK can **receive and display** screen shares initiated from web clients. Android does not support initiating screen sharing. The call layout automatically adjusts to display shared content.
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CallSession
+import com.cometchat.calls.listeners.ParticipantEventListener
+import com.cometchat.calls.model.Participant
+```
+
+## Implementation
+
+### Listen for Screen Share Events
+
+```kotlin
+val callSession = CallSession.getInstance()
+
+callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
+    override fun onParticipantStartedScreenShare(participant: Participant) {
+        Log.d(TAG, "${participant.name} started screen sharing")
+        // Layout auto-adjusts to show shared screen
+    }
+    override fun onParticipantStoppedScreenShare(participant: Participant) {
+        Log.d(TAG, "${participant.name} stopped screen sharing")
+        // Layout returns to normal
+    }
+    // ... other required overrides
+    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 onParticipantStartedRecording(participant: Participant) {}
+    override fun onParticipantStoppedRecording(participant: Participant) {}
+    override fun onParticipantHandRaised(participant: Participant) {}
+    override fun onParticipantHandLowered(participant: Participant) {}
+    override fun onDominantSpeakerChanged(participant: Participant) {}
+})
+```
+
+### Check Presenter Status
+
+```kotlin
+override fun onParticipantListChanged(participants: List<Participant>) {
+    val presenter = participants.find { it.isPresenting }
+    if (presenter != null) {
+        Log.d(TAG, "${presenter.name} is sharing their screen")
+    }
+}
+```
+
+### Show/Hide Screen Share Button
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    .hideScreenSharingButton(true)  // hide since Android can't initiate
+    .build()
+```
+
+## Gotchas
+
+- Android **cannot initiate** screen sharing — only web clients can
+- The SDK automatically adjusts the layout when a screen share starts
+- Use `participant.isPresenting` to check if someone is sharing
+- Consider hiding the screen share button on Android since it's not functional for initiating
+- `MediaEventsListener` also has `onScreenShareStarted()`/`onScreenShareStopped()` for local events
+
+## Sample App Reference
+
+- `CallActivity.kt` — Session settings configuration

package/skills/cometchat-android-v5-calls/references/server-fcm-voip.md

@@ -0,0 +1,215 @@
+# Server-side FCM HTTP v1 for Android VoIP push
+
+When a CometChat call event fires, your server sends a **high-priority FCM data message** to the recipient's Android device. The app's `FirebaseMessagingService` receives it (even when killed/backgrounded) and starts a `ConnectionService` that surfaces the OS-level incoming-call UI. Without this, Android won't ring when the app is backgrounded.
+
+**Canonical docs:** https://firebase.google.com/docs/cloud-messaging/migrate-v1, https://developer.android.com/develop/connectivity/telecom
+
+---
+
+## Hard rules
+
+1. **HTTP v1 API only.** Legacy `/fcm/send` is deprecated since 2024-06. Use `https://fcm.googleapis.com/v1/projects/{projectId}/messages:send` with OAuth2 service-account auth.
+2. **Data-only message** (no `notification` field). System notifications are throttled by Android Doze; data messages with high priority bypass.
+3. **`priority: HIGH`** + **`android.priority: HIGH`**. High priority bypasses Doze for the next 10s; long enough to get the user to answer.
+4. **Show OS UI within ~10s of receiving the data message.** Android 14+ enforces this — late notifications fail with `ERR_FOREGROUND_SERVICE_TYPE_MICROPHONE_DENIED` or get silently dropped.
+5. **`time_to_live: 30`** seconds. VoIP push must be fast or fail.
+6. **Don't include sensitive data in the payload.** Auth keys / tokens never go in the push — only `sessionId` + display strings.
+
+---
+
+## Service-account setup
+
+1. Firebase Console → Project Settings → Service accounts → "Generate new private key"
+2. Download the JSON file. Store securely (Secret Manager / Vault).
+3. The service account has `firebase.messaging` scope by default.
+
+---
+
+## Node.js template (Firebase Admin SDK)
+
+```js
+// npm install firebase-admin
+import admin from "firebase-admin";
+
+admin.initializeApp({
+  credential: admin.credential.cert(JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT_JSON)),
+});
+
+export async function sendAndroidVoipPush(opts) {
+  const { recipientUid, sessionId, callerName, callerUid, callType } = opts;
+
+  const fcmToken = await db.getFcmToken(recipientUid);
+  if (!fcmToken) return; // not on Android or token expired
+
+  const message = {
+    token: fcmToken,
+    // Data-only — see Hard Rule 2
+    data: {
+      type: "incoming_call",
+      sessionId: String(sessionId),
+      callerName: String(callerName),
+      callerUid: String(callerUid),
+      callType: String(callType), // "audio" | "video"
+      timestamp: String(Date.now()),
+    },
+    android: {
+      priority: "HIGH",      // Hard Rule 3
+      ttl: 30 * 1000,        // Hard Rule 5 — milliseconds
+    },
+  };
+
+  try {
+    await admin.messaging().send(message);
+  } catch (err) {
+    if (err.code === "messaging/registration-token-not-registered") {
+      // Token is dead — drop it
+      await db.removeFcmToken(recipientUid, fcmToken);
+      return;
+    }
+    throw err;
+  }
+}
+```
+
+---
+
+## Python template (google-auth + httpx, no Firebase Admin SDK)
+
+```python
+# pip install google-auth httpx
+import time, json, httpx
+from google.oauth2 import service_account
+from google.auth.transport.requests import Request
+
+CREDS = service_account.Credentials.from_service_account_file(
+    "/secrets/firebase-service-account.json",
+    scopes=["https://www.googleapis.com/auth/firebase.messaging"],
+)
+PROJECT_ID = os.environ["FIREBASE_PROJECT_ID"]
+FCM_URL = f"https://fcm.googleapis.com/v1/projects/{PROJECT_ID}/messages:send"
+
+def access_token() -> str:
+    if not CREDS.valid:
+        CREDS.refresh(Request())
+    return CREDS.token
+
+async def send_android_voip_push(fcm_token: str, payload: dict):
+    body = {
+        "message": {
+            "token": fcm_token,
+            "data": {k: str(v) for k, v in payload.items()},  # data values must be strings
+            "android": {"priority": "HIGH", "ttl": "30s"},
+        }
+    }
+    headers = {
+        "authorization": f"Bearer {access_token()}",
+        "content-type": "application/json",
+    }
+    async with httpx.AsyncClient() as client:
+        r = await client.post(FCM_URL, json=body, headers=headers)
+        if r.status_code == 404:
+            error = r.json().get("error", {})
+            if error.get("status") == "NOT_FOUND" or "UNREGISTERED" in str(error):
+                return "unregistered"
+        r.raise_for_status()
+```
+
+---
+
+## Receiver side (Android V5)
+
+The Android client's `FirebaseMessagingService` receives the data message and starts a `ConnectionService`:
+
+```kotlin
+class VoipMessagingService : FirebaseMessagingService() {
+  override fun onMessageReceived(message: RemoteMessage) {
+    val data = message.data
+    if (data["type"] != "incoming_call") return
+
+    val sessionId = data["sessionId"] ?: return
+    val callerName = data["callerName"] ?: "Unknown"
+    val callType = data["callType"] ?: "audio"
+
+    // Hard Rule 4 — show OS UI within ~10s
+    val telecom = getSystemService(Context.TELECOM_SERVICE) as TelecomManager
+    val handle = PhoneAccountHandle(
+      ComponentName(this, AppConnectionService::class.java),
+      "cometchat-voip"
+    )
+    val extras = Bundle().apply {
+      putString("sessionId", sessionId)
+      putString("callerName", callerName)
+      putString("callType", callType)
+    }
+    telecom.addNewIncomingCall(handle, Bundle().apply {
+      putBundle(TelecomManager.EXTRA_INCOMING_CALL_EXTRAS, extras)
+    })
+  }
+
+  override fun onNewToken(token: String) {
+    // Send to your server
+    // api.registerFcmToken(currentUserUid, token)
+  }
+}
+```
+
+Plus an `AppConnectionService extends ConnectionService` (see `cometchat-android-v5-calls/SKILL.md` rule 4). The `ConnectionService` calls `setRinging()` on the Connection, which surfaces the system incoming-call UI.
+
+---
+
+## Webhook handler shape
+
+Same as iOS — verify signature, dispatch by recipient platform:
+
+```js
+app.post("/webhooks/call", async (req, res) => {
+  if (req.body.trigger !== "call_initiated") return res.status(200).end();
+  const { sessionId, type, initiator, receiver } = req.body.data;
+  const platform = await db.getPushPlatform(receiver.uid);
+  if (platform === "ios") {
+    await sendVoipPush({ /* see cometchat-ios-calls/references/server-apns-pushkit.md */ });
+  } else if (platform === "android") {
+    await sendAndroidVoipPush({
+      recipientUid: receiver.uid,
+      sessionId, callerName: initiator.name, callerUid: initiator.uid, callType: type,
+    });
+  }
+  // Many users have multiple devices — fan out to ALL active tokens
+  res.status(200).end();
+});
+```
+
+---
+
+## Anti-patterns
+
+1. **Sending a `notification` field.** Android shows a regular system notification, doesn't wake your service. VoIP UX dies.
+2. **Skipping `priority: HIGH`.** Doze mode swallows the message until the next maintenance window — call rings 30 minutes later.
+3. **Using legacy `/fcm/send` endpoint.** Returns 401/404 since 2024-06. Migrate to HTTP v1.
+4. **Hardcoding service-account JSON in source.** Largest source of FCM credential leaks. Always env var or Secret Manager.
+5. **Forgetting to start `ConnectionService.setForeground()` from `onMessageReceived`.** Android 14+: `ForegroundServiceTypeException`. Use `setRinging()` on the Connection, which is exempt.
+6. **Storing FCM token only at app install.** FCM tokens rotate. Implement `onNewToken` and POST the new token immediately.
+
+---
+
+## Verification checklist
+
+- [ ] HTTP v1 API used (not legacy `/fcm/send`)
+- [ ] Service account JSON in Secret Manager
+- [ ] `priority: HIGH`, `ttl: 30s`, data-only payload
+- [ ] Android client `onMessageReceived` calls `addNewIncomingCall` within ~10s
+- [ ] `ConnectionService` declared in manifest with telecom permissions
+- [ ] FCM token rotation handled (`onNewToken` POSTs to your API)
+- [ ] 404/UNREGISTERED responses purge dead tokens
+- [ ] Real-device smoke: app killed → caller dials → recipient device rings + lock-screen UI
+
+---
+
+## Pointers
+
+- `cometchat-android-v5-calls/SKILL.md` — seven hard rules (init order, ConnectionService, foreground type)
+- `cometchat-android-v5-calls/references/server-fcm-voip.md` — this doc (canonical)
+- `cometchat-android-v6-calls/references/server-fcm-voip.md` — V6 sister (Compose VoIP receiver patterns)
+- `cometchat-ios-calls/references/server-apns-pushkit.md` — iOS sibling
+- FCM HTTP v1: https://firebase.google.com/docs/cloud-messaging/migrate-v1
+- Android Telecom: https://developer.android.com/develop/connectivity/telecom

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

@@ -0,0 +1,121 @@
+---
+name: session-settings
+description: Configure all SessionSettingsBuilder options — layouts, session type, audio mode, hide buttons, idle timeout, recording, camera facing. Use when customizing call UI or pre-session config. Triggers on "SessionSettingsBuilder", "session settings", "hide button", "layout type", "audio mode", "idle timeout".
+inclusion: manual
+---
+
+# CometChat Calls SDK v5 — Session Settings
+
+## Overview
+
+`SessionSettingsBuilder` configures every aspect of a call session before joining. Settings are immutable after `build()` — pass the result to `joinSession()`.
+
+## Key Imports
+
+```kotlin
+import com.cometchat.calls.core.CometChatCalls
+import com.cometchat.calls.model.SessionType   // VIDEO, VOICE
+import com.cometchat.calls.model.LayoutType    // TILE, SIDEBAR, SPOTLIGHT
+import com.cometchat.calls.model.AudioMode     // SPEAKER, EARPIECE, BLUETOOTH, HEADPHONES
+import com.cometchat.calls.model.CameraFacing  // FRONT, BACK
+```
+
+## Implementation
+
+### Full Builder Example
+
+```kotlin
+val sessionSettings = CometChatCalls.SessionSettingsBuilder()
+    // Identity
+    .setTitle("Team Meeting")
+    .setDisplayName("John Doe")
+
+    // Session type & layout
+    .setSessionType(SessionType.VIDEO)       // VIDEO or VOICE
+    .setLayout(LayoutType.TILE)              // TILE, SIDEBAR, or SPOTLIGHT
+
+    // Initial media state
+    .startAudioMuted(false)
+    .startVideoPaused(false)
+    .setAudioMode(AudioMode.SPEAKER)         // SPEAKER, EARPIECE, BLUETOOTH, HEADPHONES
+    .setInitialCameraFacing(CameraFacing.FRONT) // FRONT or BACK
+
+    // Timeout & recording
+    .setIdleTimeoutPeriod(300)               // seconds (default 300)
+    .enableAutoStartRecording(false)
+
+    // Hide panels
+    .hideControlPanel(false)
+    .hideHeaderPanel(false)
+    .hideSessionTimer(false)
+
+    // Hide individual buttons
+    .hideLeaveSessionButton(false)
+    .hideToggleAudioButton(false)
+    .hideToggleVideoButton(false)
+    .hideSwitchCameraButton(false)
+    .hideRecordingButton(true)               // hidden by default
+    .hideAudioModeButton(false)
+    .hideRaiseHandButton(false)
+    .hideShareInviteButton(true)             // hidden by default
+    .hideParticipantListButton(false)
+    .hideChangeLayoutButton(false)
+    .hideChatButton(true)                    // hidden by default
+
+    .build()
+```
+
+### Enum Values Reference
+
+| Enum | Values |
+|------|--------|
+| `SessionType` | `VIDEO`, `VOICE` |
+| `LayoutType` | `TILE`, `SIDEBAR`, `SPOTLIGHT` |
+| `AudioMode` | `SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES` |
+| `CameraFacing` | `FRONT`, `BACK` |
+
+### Common Presets
+
+**Voice call:**
+```kotlin
+.setSessionType(SessionType.VOICE)
+.setLayout(LayoutType.SPOTLIGHT)
+.setAudioMode(AudioMode.EARPIECE)
+.startVideoPaused(true)
+```
+
+**Video call:**
+```kotlin
+.setSessionType(SessionType.VIDEO)
+.setLayout(LayoutType.TILE)
+.setAudioMode(AudioMode.SPEAKER)
+.startVideoPaused(false)
+```
+
+**Custom UI (hide default controls):**
+```kotlin
+.hideControlPanel(true)
+.hideHeaderPanel(true)
+```
+
+### Button Defaults
+
+| Button | Default Hidden? |
+|--------|----------------|
+| Recording | Yes (`true`) |
+| Share Invite | Yes (`true`) |
+| Chat | Yes (`true`) |
+| All others | No (`false`) |
+
+## Gotchas
+
+- Settings are **immutable** after `build()` — create a new builder for changes
+- `SessionType` uses `VOICE` not "AUDIO"
+- `LayoutType` values: `TILE`, `SIDEBAR`, `SPOTLIGHT` — all caps
+- `setIdleTimeoutPeriod()` takes seconds, default is 300 (5 minutes)
+- Recording, share invite, and chat buttons are hidden by default
+- These are pre-session configs only; use `CallSession` actions for runtime changes
+
+## Sample App Reference
+
+- `CallActivity.kt` — `joinSession()` method builds settings based on voice/video call type