@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-flutter-v5-calls/references/device-management.md

@@ -0,0 +1,120 @@
+# Device management on Flutter V5 (GetX)
+
+The Calls SDK exposes basic camera switching (`switchCamera()`); audio device management goes through platform-channel bridges to native AVAudioSession (iOS) / AudioManager (Android). For most apps, the kit's default control panel handles this; custom UI uses `flutter_callkit_incoming` or platform channels.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/device-management
+**Read first:** `cometchat-react-calls/references/device-management.md` — UX patterns; the SDK conceptual model carries over.
+
+---
+
+## SDK API
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+// Camera flip
+CometChatCalls.switchCamera();
+
+// Speaker toggle (iOS + Android — wraps native AudioManager / AVAudioSession)
+CometChatCalls.setSpeakerEnabled(true);
+```
+
+---
+
+## Audio routing — flutter_callkit_incoming
+
+For Bluetooth / AirPods routing, integrate `flutter_callkit_incoming` which wraps native CallKit on iOS and ConnectionService on Android. It exposes the audio route picker:
+
+```dart
+import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart';
+
+// Toggle speaker
+await FlutterCallkitIncoming.setAudioRoute(AudioRoute.speaker);
+await FlutterCallkitIncoming.setAudioRoute(AudioRoute.earpiece);
+```
+
+For deep AirPods / Bluetooth control, the recommended pattern is letting the OS handle it via the system audio picker (CallKit on iOS, ConnectionService on Android both expose audio route control natively).
+
+---
+
+## Camera flip button
+
+```dart
+class CameraFlipButton extends StatelessWidget {
+  const CameraFlipButton({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return IconButton(
+      icon: const Icon(Icons.flip_camera_ios),
+      onPressed: () {
+        CometChatCalls.switchCamera();
+        SemanticsService.announce('Camera flipped', TextDirection.ltr);
+      },
+      tooltip: 'Flip camera',
+    );
+  }
+}
+```
+
+---
+
+## Speaker toggle
+
+```dart
+class SpeakerToggle extends GetView<CallController> {
+  const SpeakerToggle({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Obx(() => IconButton(
+      icon: Icon(controller.speakerOn.value
+        ? Icons.volume_up
+        : Icons.hearing),
+      onPressed: () {
+        controller.toggleSpeaker();
+      },
+      tooltip: controller.speakerOn.value ? 'Switch to earpiece' : 'Switch to speaker',
+    ));
+  }
+}
+
+class CallController extends GetxController {
+  final speakerOn = false.obs;
+
+  void toggleSpeaker() {
+    speakerOn.value = !speakerOn.value;
+    CometChatCalls.setSpeakerEnabled(speakerOn.value);
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Flutter-specific:
+
+1. **Custom UI for audio device selection** instead of letting CallKit / ConnectionService handle it. System picker is what users expect.
+2. **Calling `switchCamera` inline without await on the SDK promise.** Some platforms queue the switch; back-to-back calls drop.
+3. **Forgetting `flutter_callkit_incoming.setAudioRoute` doesn't work without an active call session.** Call must be live.
+
+---
+
+## Verification checklist
+
+- [ ] Camera flip wired to `CometChatCalls.switchCamera()`
+- [ ] Speaker toggle uses `setSpeakerEnabled`
+- [ ] System audio route picker (CallKit / ConnectionService) preferred for Bluetooth
+- [ ] Real-device smoke: speaker toggle works
+- [ ] Real-device smoke: camera flip works
+- [ ] AirPods smoke: connecting AirPods routes audio (CallKit/ConnectionService handles)
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/device-management.md` — sister web reference (UX shape)
+- `cometchat-flutter-v5-calls` SKILL.md — V5 hard rules
+- `references/voip-push-end-to-end.md` (if you have it) — flutter_callkit_incoming setup
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/device-management

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

@@ -0,0 +1,187 @@
+# Group calls — broadcast meeting pattern (Flutter V5)
+
+Group calls 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.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/group-calls
+
+V5 specifics: Flutter V5 uses `cometchat_chat_uikit ^5.2` + `cometchat_calls_uikit ^5.0` (separate calls package). GetX-based state. The signaling semantic below is identical to Flutter V6.
+
+---
+
+## Architecture
+
+```
+Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
+  │                                       │                              │
+  │ CometChatCallButtons sends            │                              │
+  │ CustomMessage(GUID, GROUP, "meeting", │                              │
+  │   { callType, sessionId })            │                              │
+  ├──────────────────────────────────────>│                              │
+  │                                       │ onCustomMessageReceived      │
+  │                                       ├─────────────────────────────>│
+  │ caller pushes OngoingCallScreen       │  receiver taps Join          │
+  │  with sessionID = groupGuid           │  → CometChatUIKitCalls       │
+  │                                       │    .startSession(...)        │
+  ├──────────────────────────────────────>│ <─────────────────────────── │
+  │            ───── 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 |
+
+---
+
+## Hard rules
+
+1. **Group calls broadcast a custom message; they do NOT use the call listener.** Custom UI must add a `MessageListener`.
+2. **Session ID = group GUID.** Persistent.
+3. **`CometChatUIKitCalls.init()` must complete AFTER `CometChatUIKit.init()`** (CALLS_INIT_AFTER_CHAT_INIT rule from SKILL.md) — same as 1:1.
+4. **No `CometChat.endCall` for groups.** Use `CometChatUIKitCalls.endSession()` only.
+
+---
+
+## Caller side — kit-based
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+// Inside a chat surface (e.g. inside CometChatMessageHeader):
+CometChatCallButtons(
+  group: group,
+)
+```
+
+Tap → kit sends meeting `CustomMessage` + pushes outgoing-call screen → transitions to ongoing call with `sessionId = group.guid`.
+
+## Caller side — custom UI
+
+```dart
+import 'package:flutter_chat_sdk/flutter_chat_sdk.dart';
+
+Future<void> startGroupCall(String groupGuid, String callType) async {
+  final sessionId = groupGuid;
+  final customData = {'callType': callType, 'sessionId': sessionId};
+
+  final meetingMessage = CustomMessage(
+    receiverUid: groupGuid,
+    receiverType: CometChatReceiverType.group,
+    customData: customData,
+    type: 'meeting',
+  )
+    ..category = MessageCategoryConstants.custom
+    ..metadata = {
+      'incrementUnreadCount': true,
+      'pushNotification': 'meeting',
+      ...customData,
+    };
+
+  await CometChat.sendCustomMessage(
+    meetingMessage,
+    onSuccess: (msg) {
+      // Navigate to OngoingCall screen with sessionId
+      Navigator.of(context).pushNamed('/ongoing-call', arguments: {
+        'sessionId': sessionId,
+        'callType': callType,
+      });
+    },
+    onError: (e) {/* surface error */},
+  );
+}
+```
+
+---
+
+## Receiver side — kit-based
+
+`CometChatMessageList(group: group)` auto-renders the meeting message as a "Join meeting" card. Tap → kit calls `generateToken` and pushes the ongoing-call screen with `sessionId = group.guid`.
+
+## Receiver side — custom UI
+
+```dart
+import 'package:flutter_chat_sdk/flutter_chat_sdk.dart';
+
+const groupMeetingListenerId = 'APP_ROOT_GROUP_MEETING_LISTENER';
+
+void registerGroupMeetingListener() {
+  CometChat.addMessageListener(
+    groupMeetingListenerId,
+    MessageListener(
+      onCustomMessageReceived: (msg) {
+        if (msg.category != MessageCategoryConstants.custom) return;
+        if (msg.type != 'meeting') return;
+
+        final customData = msg.customData ?? {};
+        final sessionId = customData['sessionId'] as String? ?? msg.receiverUid;
+        final callType = customData['callType'] as String? ?? 'video';
+        final fromUid = msg.sender?.uid;
+        final groupGuid = msg.receiverUid;
+
+        // Update your state (GetX controller, Provider, Riverpod):
+        // Get.find<CallController>().receiveIncomingMeeting(
+        //   sessionId: sessionId, callType: callType, fromUid: fromUid, groupGuid: groupGuid,
+        // );
+      },
+    ),
+  );
+}
+
+void unregisterGroupMeetingListener() {
+  CometChat.removeMessageListener(groupMeetingListenerId);
+}
+```
+
+Wire register in `initState` / GetX controller `onInit`, unregister in `dispose` / `onClose`. Register AFTER `CometChatUIKit.login()` succeeds.
+
+---
+
+## Edge cases
+
+### Late joining
+
+Meeting persists in chat. Tap any time to join the live session.
+
+### Push notifications (FCM Android, APNs / VoIP iOS)
+
+Meeting `CustomMessage.metadata.pushNotification = "meeting"` — delivered as regular FCM/APNs notification. To get CallKit (iOS) or ConnectionService (Android) ringing for meetings, intercept the push payload and route to `flutter_callkit_incoming` manually. Not auto-wired.
+
+### `navigatorKey` requirement (V5 too)
+
+If you use the kit's outgoing-call screen for groups, ensure `MaterialApp` has `navigatorKey: CallNavigationContext.navigatorKey` — same requirement as 1:1 (rule 1.7 in SKILL.md).
+
+---
+
+## Anti-patterns
+
+1. **Only `CometChat.addCallListener` registered, expecting group calls to ring.** Add `addMessageListener` too.
+2. **`CometChat.endCall(sessionId)` after a group hangup.** No call entity exists.
+3. **Treating sessionId as ephemeral.** It IS the group's GUID.
+4. **Registering `MessageListener` before login.** Listeners registered pre-login are silently dropped. Wire AFTER `CometChatUIKit.login` completes.
+5. **Skipping the `navigatorKey` for the meeting flow.** Same context-navigation requirement as 1:1.
+
+---
+
+## Verification checklist
+
+- [ ] If using kit caller: `CometChatCallButtons(group: group)` tap initiates meeting message
+- [ ] If using custom caller: `CometChat.sendCustomMessage` called with `type: 'meeting'`, `category: MessageCategoryConstants.custom`, `customData: {callType, sessionId}`, `metadata: { pushNotification: 'meeting' }`
+- [ ] If using kit receiver: `CometChatMessageList(group: group)` renders meeting card
+- [ ] If using custom receiver: `CometChat.addMessageListener` registered with category+type filter, AFTER login
+- [ ] `MaterialApp.navigatorKey = CallNavigationContext.navigatorKey` set (kit-driven UI path)
+- [ ] On hangup: `CometChatUIKitCalls.endSession()` only (no `CometChat.endCall`)
+- [ ] Late-joining tested
+- [ ] Push notifications fire for offline members
+
+---
+
+## Pointers
+
+- `ringing-integration.md` — 1:1 user calls (different signaling channel)
+- `cometchat-flutter-v5-calls/SKILL.md` — V5 hard rules (cometchat_calls_uikit peer, Jetifier, etc.)
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/group-calls
+- Cross-platform reference (semantic ground-truth): `cometchat-react-calls/references/group-calls.md`

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

@@ -0,0 +1,97 @@
+# Idle timeout on Flutter V5 (GetX-based)
+
+Same SDK API. Flutter-specific: `CallSettingsBuilder` setter API + `showDialog` / overlay for the prompt.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/idle-timeout
+**Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts.
+
+---
+
+## SDK API
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+final settings = CallSettingsBuilder()
+  ..setIdleTimeoutPeriodBeforePrompt = 60000
+  ..setIdleTimeoutPeriodAfterPrompt = 120000;
+final builtSettings = settings.build();
+```
+
+Listener — implement on the GetX controller (cf. `references/raise-hand.md`):
+
+```dart
+class CallController extends GetxController implements CometChatCallsEventsListener {
+  @override
+  void onSessionTimedOut() {
+    Get.snackbar('Call ended', 'You were inactive for too long');
+    Get.until((route) => route.isFirst);  // pop to home
+  }
+  // ... other handlers
+}
+```
+
+---
+
+## Custom prompt — showDialog
+
+```dart
+Future<void> showIdleTimeoutPrompt(BuildContext context) async {
+  final result = await showDialog<String>(
+    context: context,
+    barrierDismissible: false,  // prevent tap-outside dismiss
+    builder: (ctx) => AlertDialog(
+      title: const Text('Still there?'),
+      content: const Text("You're alone in this call. It'll end in 60 seconds."),
+      actions: [
+        TextButton(
+          onPressed: () => Navigator.pop(ctx, 'end'),
+          child: const Text('End now', style: TextStyle(color: Colors.red)),
+        ),
+        FilledButton(
+          onPressed: () => Navigator.pop(ctx, 'stay'),
+          child: const Text('Stay'),
+        ),
+      ],
+    ),
+  );
+
+  if (result == 'end') {
+    // CometChatCalls.endSession() does NOT exist on Flutter — use the CallSession instance.
+    await CallSession.getInstance().leaveSession();
+  } else {
+    // 'stay' or null — reset custom timer
+  }
+}
+```
+
+`barrierDismissible: false` prevents accidental dismiss; user must explicitly pick.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Flutter-specific:
+
+1. **`Get.dialog` from inside a non-context method** without a captured BuildContext. Dialog opens but has no theme/context — looks broken.
+2. **`Navigator.pop` with no result.** Subsequent code can't differentiate stay vs end. Always pass result.
+3. **Showing prompt while ongoing-call view is being disposed.** Race condition. Check `mounted` before showing.
+
+---
+
+## Verification checklist
+
+- [ ] CallSettingsBuilder sets both idle periods
+- [ ] `onSessionTimedOut` snackbar + nav cleanup
+- [ ] Dialog `barrierDismissible: false`
+- [ ] `mounted` check before showing prompt
+- [ ] Real-device smoke: 2 devices, hangup one → prompt fires + nav home after timeout
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/idle-timeout.md` — sister reference
+- `cometchat-flutter-v5-calls` SKILL.md
+- `cometchat-flutter-v5-calls/references/raise-hand.md` — sibling V5 GetX pattern
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/idle-timeout

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

@@ -0,0 +1,132 @@
+# In-call chat on Flutter V5 (GetX)
+
+Same SDK shape. Flutter-specific: `showModalBottomSheet` with `isScrollControlled: true` for the panel + `MediaQuery.viewInsets` for keyboard handling.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/in-call-chat
+**Read first:** `cometchat-react-calls/references/in-call-chat.md` — group-as-session architecture.
+
+---
+
+## SDK API
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+// Wire chat button visibility via the call settings builder
+final settings = CallSettingsBuilder()
+  ..hideChatButton = false;
+
+// In your CometChatCallsEventsListener:
+@override
+void onChatButtonClicked() {
+  Get.find<CallController>().openChat();
+}
+
+CometChatCalls.setChatButtonUnreadCount(5);
+```
+
+---
+
+## Group-as-session helper
+
+```dart
+Future<Group> ensureCallGroup(String sessionId) async {
+  try {
+    return await CometChatGroups.getGroup(sessionId);
+  } catch (_) {
+    final group = Group(
+      guid: sessionId,
+      name: 'Call $sessionId',
+      type: GroupTypeConstants.public,
+    );
+    return await CometChatGroups.createGroup(group);
+  }
+}
+```
+
+---
+
+## Modal bottom sheet panel
+
+```dart
+class CallController extends GetxController {
+  final unread = 0.obs;
+  Group? group;
+
+  Future<void> initChat(String sessionId) async {
+    group = await ensureCallGroup(sessionId);
+    // Track unread...
+  }
+
+  void openChat() {
+    if (group == null) return;
+    Get.bottomSheet(
+      InCallChatPanel(group: group!),
+      isScrollControlled: true,           // allow full-height
+      barrierColor: Colors.transparent,   // call view stays visible
+      enableDrag: true,
+    );
+    unread.value = 0;
+    CometChatCalls.setChatButtonUnreadCount(0);
+  }
+}
+
+class InCallChatPanel extends StatelessWidget {
+  final Group group;
+  const InCallChatPanel({super.key, required this.group});
+
+  @override
+  Widget build(BuildContext context) {
+    final keyboardHeight = MediaQuery.of(context).viewInsets.bottom;
+    return Padding(
+      padding: EdgeInsets.only(bottom: keyboardHeight),
+      child: Container(
+        height: MediaQuery.of(context).size.height * 0.7,
+        decoration: const BoxDecoration(
+          color: Colors.white,
+          borderRadius: BorderRadius.vertical(top: Radius.circular(16)),
+        ),
+        child: Column(
+          children: [
+            const ListTile(title: Text('Chat')),
+            Expanded(child: CometChatMessageList(group: group)),
+            CometChatMessageComposer(group: group),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+`MediaQuery.viewInsets.bottom` accounts for keyboard height; the sheet pushes up correctly when typing.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Flutter-specific:
+
+1. **`Get.bottomSheet` without `isScrollControlled: true`.** Sheet capped at half-screen, can't expand for full chat.
+2. **`barrierColor: Colors.black54`.** Default dim; call view obscured. Use `Colors.transparent` for in-call.
+3. **`Expanded` direct children of `Column` without considering composer height.** Padding via `MediaQuery.viewInsets` handles it cleanly.
+
+---
+
+## Verification checklist
+
+- [ ] `hideChatButton = false` in CallSettings
+- [ ] `onChatButtonClicked` opens bottom sheet
+- [ ] `Get.bottomSheet` uses `isScrollControlled: true` + transparent barrier
+- [ ] `MediaQuery.viewInsets.bottom` padding for keyboard
+- [ ] Group resolved before opening sheet
+- [ ] Real-device smoke: keyboard opens during chat, sheet adjusts
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/in-call-chat.md` — sister
+- `cometchat-flutter-v5-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/in-call-chat

package/skills/cometchat-flutter-v5-calls/references/migration-v4-to-v5.md

@@ -0,0 +1,160 @@
+# CometChat Calls Flutter SDK v4 → v5 migration
+
+`cometchat_calls_uikit: ^5.0.15` is the v5 calls package for Flutter — drop-in replacement for the v4 calls SDK.
+
+**Important:** This migrates the **Calls SDK** (v4 → v5), not the UI Kit cohort (V5 GetX → V6 Bloc, which is `cometchat-flutter-v6-migration`). You can be on UI Kit V5 + Calls SDK v5 — they version independently.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/migration-guide-v5
+
+---
+
+## Step 1 — Bump pubspec
+
+```yaml
+# pubspec.yaml
+dependencies:
+  cometchat_calls_uikit: ^5.0.15
+```
+
+```bash
+flutter pub get
+cd ios && pod install     # if you have iOS
+```
+
+---
+
+## Step 2 — Migrate init
+
+```diff
+- final callSettings = CallAppSettingsBuilder()
+-   ..setAppId('APP_ID')
+-   ..setRegion('REGION');
+- await CometChatCalls.init(callSettings);
+
++ final settings = CallAppSettings(appId: 'APP_ID', region: 'REGION');
++ await CometChatCalls.init(settings);
+```
+
+---
+
+## Step 3 — Add Calls SDK login
+
+```dart
+// After CometChat.login completes
+final user = (await CometChatUIKit.getLoggedInUser())!;
+final authToken = user.authToken;
+await CometChatCalls.login(authToken: authToken);
+```
+
+---
+
+## Step 4 — Migrate session settings
+
+```diff
+- final callSettings = CallSettingsBuilder()
+-   ..setSessionType(SessionType.video)
+-   ..startWithAudioMuted(false)
+-   ..showRecordingButton(true);
+
++ final sessionSettings = SessionSettings(
++   sessionType: SessionType.video,
++   startAudioMuted: false,
++   hideRecordingButton: false,    // INVERTED
++   layout: CallLayout.tile,
++ );
+```
+
+---
+
+## Step 5 — Migrate listener to event subscriptions
+
+```diff
+- class MyEvents implements CometChatCallsEventsListener {
+-   @override
+-   void onCallEnded() { /* ... */ }
+-   @override
+-   void onUserJoined(User user) { /* ... */ }
+-   // ...
+- }
+- CometChatCalls.addCallsEventsListener('id', MyEvents());
+
++ final unsub1 = CometChatCalls.addEventListener(CallEvent.sessionLeft, () { /* ... */ });
++ final unsub2 = CometChatCalls.addEventListener(CallEvent.participantJoined, (participant) { /* ... */ });
++ final unsub3 = CometChatCalls.addEventListener(CallEvent.participantLeft, (participant) { /* ... */ });
++
++ @override
++ void dispose() {
++   unsub1.call();
++   unsub2.call();
++   unsub3.call();
++   super.dispose();
++ }
+```
+
+---
+
+## Step 6 — Method renames + receiver shift
+
+v5 moved most call-control APIs from static methods on `CometChatCalls` to **instance methods on `CallSession`** (the singleton fetched via `CallSession.getInstance()`). The static `endSession()` is preserved as a deprecated shim — the others were removed.
+
+```diff
+// session lifecycle — receiver changes from CometChatCalls (static) to CallSession (singleton)
+- CometChatCalls.endSession()
++ await CallSession.getInstance()?.leaveSession()
+
+// media controls — same receiver shift
+- CometChatCalls.muteAudio(true)
++ CallSession.getInstance()?.muteAudio()
+- CometChatCalls.muteAudio(false)
++ CallSession.getInstance()?.unmuteAudio()
+
+- CometChatCalls.startScreenShare()
++ CallSession.getInstance()?.startScreenShare()
+
+// layout stays static
+- CometChatCalls.setMode(mode)
++ CometChatCalls.setLayout(layout)
+```
+
+**`CallSession.getInstance()` returns `CallSession?` (nullable)** — null when there's no active session. Use `?.` to safely chain; calling on null is a no-op.
+
+---
+
+## Step 7 — GetX state preservation
+
+If you're using GetX controllers around the calls (per `cometchat-flutter-v5-calls/SKILL.md`), the state shape doesn't change — only the underlying SDK calls. Sample diff in a GetX controller:
+
+```diff
+  class CallController extends GetxController {
+    void startCall(String sessionId) async {
+-     await CometChatCalls.startSession(sessionId, settings: callSettings);
++     await CometChatCalls.joinSession(sessionId, settings: sessionSettings);
+    }
+
+    void endCall() async {
+-     CometChatCalls.endSession();
++     await CallSession.getInstance()?.leaveSession();
+    }
+  }
+```
+
+---
+
+## Verification checklist
+
+- [ ] `pubspec.yaml` lists `cometchat_calls_uikit: ^5.0.15` (or higher)
+- [ ] `flutter pub get` + `pod install` succeed
+- [ ] `CometChatCalls.login(authToken:)` called after `CometChat.login`
+- [ ] CallSettingsBuilder replaced with `SessionSettings`
+- [ ] CometChatCallsEventsListener replaced with `addEventListener`
+- [ ] Method renames applied
+- [ ] GetX controllers updated to v5 method names
+- [ ] Real-device smoke: iOS + Android, incoming/outgoing/mute/screenshare
+
+---
+
+## Pointers
+
+- Canonical migration: https://www.cometchat.com/docs/calls/flutter/migration-guide-v5
+- `cometchat-flutter-v5-calls/SKILL.md` — Flutter calls architecture (GetX patterns)
+- `cometchat-flutter-v6-calls/` — V6 cohort (Bloc); V6 starts on Calls SDK v5 — no migration needed