@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,124 +0,0 @@
-# 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
-
-Camera switching and audio-output selection are **instance methods on the `CallSession` singleton** (`cometchat_calls_sdk-5.0.2` `src/call_session.dart`). There is no `setSpeakerEnabled` in 5.x — audio output is chosen via `setAudioModeType(AudioMode)` where `AudioMode { speaker, earpiece, bluetooth }` (`src/enums/audio_mode.dart`).
-
-```dart
-import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
-
-// Camera flip
-CallSession.getInstance()?.switchCamera();             // call_session.dart:205
-
-// Audio output (speaker / earpiece / bluetooth)
-CallSession.getInstance()?.setAudioModeType(AudioMode.speaker);   // call_session.dart:381
-```
-
----
-
-## 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: () {
-        CallSession.getInstance()?.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;
-    CallSession.getInstance()?.setAudioModeType(
-      speakerOn.value ? AudioMode.speaker : AudioMode.earpiece,
-    );
-  }
-}
-```
-
----
-
-## 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 `CallSession.getInstance()?.switchCamera()`
-- [ ] Speaker toggle uses `CallSession.getInstance()?.setAudioModeType(AudioMode.speaker | .earpiece)`
-- [ ] 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

@@ -1,181 +0,0 @@
-# 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, broadcast a **custom message of type `"meeting"`** to the group; receivers handle it via `MessageListener.onCustomMessageReceived` and join the WebRTC session whose `sessionId = group GUID`.
-
-By-design signaling semantic — same 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` (GetX chat kit) + the **raw `cometchat_calls_sdk ^5.0.2`** (direct dependency) — you build a custom meeting/ongoing-call surface. The signaling semantic below is identical to Flutter V6.
-
----
-
-## Architecture
-
-```
-Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
-  │                                       │                              │
-  │ sendCustomMessage(GUID, GROUP,        │                              │
-  │   "meeting", { callType, sessionId }) │                              │
-  ├──────────────────────────────────────>│                              │
-  │                                       │ onCustomMessageReceived      │
-  │                                       ├─────────────────────────────>│
-  │ caller pushes OngoingCallScreen       │  receiver taps Join          │
-  │  with sessionID = groupGuid           │  → CometChatCalls            │
-  │                                       │    .joinSession(...)         │
-  ├──────────────────────────────────────>│ <─────────────────────────── │
-  │            ───── 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.** Add a `MessageListener`.
-2. **Session ID = group GUID.** Persistent.
-3. **`CometChatCalls.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 `CallSession.getInstance()?.leaveSession()` only.
-
----
-
-## 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 — 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.
-
-On Join tap, join the WebRTC session with the group GUID as the sessionId (5.x raw SDK):
-
-```dart
-CometChatCalls.joinSession(            // cometchatcalls.dart:735
-  sessionId: groupGuid,                // sessionId == group GUID
-  sessionSettings: (SessionSettingsBuilder()..setTitle('Meeting')).build(),
-  onSuccess: (Widget? widget) { /* render via SizedBox.expand */ },
-  onError: (CometChatCallsException e) { /* surface */ },
-);
-```
-
-> **Legacy 4.x-kit alternative (incompatible with the 5.x calls SDK).** The old `cometchat_calls_uikit` path used `CometChatCallButtons(group: group)` for the caller, auto-rendered the meeting card in `CometChatMessageList(group: group)`, and joined via `CometChatUIKitCalls.startSession`. Those widgets are 4.x-bound and cannot run against `cometchat_calls_sdk ^5.0.2` — replicate with the custom-message + `joinSession` flow above.
-
----
-
-## 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)
-
-Set `MaterialApp.navigatorKey` to a plain `GlobalKey<NavigatorState>` so the meeting flow can navigate from anywhere — same requirement as 1:1 (rule 1.7 in SKILL.md). (Do NOT use `CallNavigationContext.navigatorKey` — that is a 4.x-kit symbol.)
-
----
-
-## 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
-
-- [ ] Caller: `CometChat.sendCustomMessage` called with `type: 'meeting'`, `category: MessageCategoryConstants.custom`, `customData: {callType, sessionId}`, `metadata: { pushNotification: 'meeting' }`
-- [ ] Receiver: `CometChat.addMessageListener` registered with category+type filter, AFTER login
-- [ ] Join action calls `CometChatCalls.joinSession(sessionId: groupGuid, ...)`
-- [ ] `MaterialApp.navigatorKey` is a `GlobalKey<NavigatorState>`
-- [ ] On hangup: `CallSession.getInstance()?.leaveSession()` 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 (raw `cometchat_calls_sdk ^5.0.2`, 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

@@ -1,99 +0,0 @@
-# Idle timeout on Flutter V5 (GetX-based, 5.x Calls SDK)
-
-Flutter-specific: `SessionSettingsBuilder` 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
-
-In 5.x the idle period is a single value (in **seconds**) on `SessionSettingsBuilder` — `setIdleTimeoutPeriod(int timeoutSeconds)` (`cometchat_calls_sdk-5.0.2` `src/builder/session_settings.dart:185`). There is no separate before/after-prompt split.
-
-```dart
-import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
-
-final settings = (SessionSettingsBuilder()
-      ..setIdleTimeoutPeriod(180))   // seconds — session_settings.dart:185
-    .build();
-```
-
-Listener — implement `SessionStatusListeners` on the GetX controller (cf. `references/raise-hand.md`); `onSessionTimedOut` is `src/listener/session_status_listeners.dart:22`:
-
-```dart
-class CallController extends GetxController implements SessionStatusListeners {
-  @override
-  void onSessionTimedOut() {
-    Get.snackbar('Call ended', 'You were inactive for too long');
-    Get.until((route) => route.isFirst);  // pop to home
-  }
-  // ... other SessionStatusListeners handlers (no-ops or pass-through)
-}
-```
-
----
-
-## 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') {
-    // 5.x teardown: the CallSession INSTANCE leaveSession() (call_session.dart:272).
-    // The static CometChatCalls.endSession exists but is @Deprecated.
-    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
-
-- [ ] `SessionSettingsBuilder()..setIdleTimeoutPeriod(seconds)` (single value, in seconds)
-- [ ] `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

@@ -1,135 +0,0 @@
-# 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_sdk/cometchat_calls_sdk.dart';
-import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-
-// Wire chat button visibility via the (non-deprecated) SessionSettingsBuilder
-final settings = (SessionSettingsBuilder()
-      ..hideChatButton(false))   // session_settings.dart:299
-    .build();
-
-// The chat-button tap arrives on ButtonClickListeners (src/listener/button_click_listeners.dart:34),
-// registered via CallSession.getInstance()?.addButtonClickListener(...) (call_session.dart:90):
-@override
-void onChatButtonClicked() {
-  Get.find<CallController>().openChat();
-}
-
-// Unread badge — INSTANCE method on the session singleton (call_session.dart:489):
-CallSession.getInstance()?.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;
-    CallSession.getInstance()?.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
-
-- [ ] `SessionSettingsBuilder()..hideChatButton(false)`
-- [ ] `onChatButtonClicked` (ButtonClickListeners, registered on `CallSession.getInstance()`) 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