@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-flutter-v5-calls/references/raise-hand.md

@@ -0,0 +1,244 @@
+# Raise hand on Flutter (UIKit V5, GetX-based)
+
+Same SDK conceptual API as web/native. Flutter V5 uses GetX for state management — the canonical pattern is a `GetxController` that wraps the call event listener and publishes raised-hand state via `Rx<List<RaisedParticipant>>`.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/raise-hand
+**Read first:** `cometchat-react-calls/references/raise-hand.md` — UX shape + anti-patterns are identical; this is the V5 GetX-specific wiring.
+
+---
+
+## SDK API
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+// Local user
+CometChatCalls.raiseHand();
+CometChatCalls.lowerHand();
+
+// Listener — registered via the call event listener attached to the OngoingCall widget
+class CallListener implements CometChatCallsEventsListener {
+  @override
+  void onParticipantHandRaised(Participant participant) {
+    // participant.uid, participant.name
+  }
+
+  @override
+  void onParticipantHandLowered(Participant participant) {
+    // ...
+  }
+  // ... other event handlers
+}
+
+// Settings flag
+final settings = CallSettingsBuilder()
+  ..hideRaiseHandButton = true;
+final builtSettings = settings.build();
+```
+
+---
+
+## GetX controller
+
+```dart
+import 'package:get/get.dart';
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+class RaisedParticipant {
+  final String uid;
+  final String name;
+  final DateTime raisedAt;
+  RaisedParticipant({required this.uid, required this.name, required this.raisedAt});
+}
+
+class RaiseHandController extends GetxController implements CometChatCallsEventsListener {
+  final localRaised = false.obs;
+  final raised = <RaisedParticipant>[].obs;
+
+  void toggle() {
+    if (localRaised.value) {
+      CometChatCalls.lowerHand();
+    } else {
+      CometChatCalls.raiseHand();
+    }
+    localRaised.value = !localRaised.value;
+  }
+
+  @override
+  void onParticipantHandRaised(Participant p) {
+    final entry = RaisedParticipant(
+      uid: p.uid, name: p.name, raisedAt: DateTime.now(),
+    );
+    raised.removeWhere((r) => r.uid == p.uid);
+    raised.add(entry);
+    raised.sort((a, b) => a.raisedAt.compareTo(b.raisedAt));
+  }
+
+  @override
+  void onParticipantHandLowered(Participant p) {
+    raised.removeWhere((r) => r.uid == p.uid);
+  }
+
+  // ... implement other CometChatCallsEventsListener methods (no-ops or pass-through)
+}
+```
+
+`.obs` is GetX's reactive marker. UI rebuilds automatically when these mutate.
+
+---
+
+## Toggle button widget
+
+```dart
+class RaiseHandButton extends StatelessWidget {
+  const RaiseHandButton({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final ctrl = Get.find<RaiseHandController>();
+    return Obx(() => GestureDetector(
+      onTap: () {
+        ctrl.toggle();
+        // Announce for screen readers
+        SemanticsService.announce(
+          ctrl.localRaised.value ? 'Hand raised' : 'Hand lowered',
+          TextDirection.ltr,
+        );
+      },
+      child: Semantics(
+        button: true,
+        selected: ctrl.localRaised.value,
+        label: ctrl.localRaised.value ? 'Lower hand' : 'Raise hand',
+        child: Container(
+          padding: const EdgeInsets.all(12),
+          decoration: BoxDecoration(
+            color: ctrl.localRaised.value
+              ? const Color(0xFFFFD60A)
+              : Colors.white24,
+            borderRadius: BorderRadius.circular(32),
+          ),
+          child: Row(
+            children: [
+              const Text('✋'),
+              const SizedBox(width: 4),
+              Text(ctrl.localRaised.value ? 'Lower' : 'Raise'),
+            ],
+          ),
+        ),
+      ),
+    ));
+  }
+}
+```
+
+`SemanticsService.announce` is the Flutter equivalent of `aria-live` / `UIAccessibility.post(.announcement, ...)` — TalkBack and VoiceOver pick up the announcement.
+
+`Semantics` wrapper sets `button: true`, `selected:`, `label:` — these map to platform a11y conventions.
+
+---
+
+## Raised-hands sheet (DraggableScrollableSheet)
+
+```dart
+class RaisedHandsSheet extends StatelessWidget {
+  const RaisedHandsSheet({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final ctrl = Get.find<RaiseHandController>();
+    return DraggableScrollableSheet(
+      initialChildSize: 0.1,
+      minChildSize: 0.1,
+      maxChildSize: 0.5,
+      builder: (context, scrollController) => Container(
+        decoration: const BoxDecoration(
+          color: Colors.white,
+          borderRadius: BorderRadius.vertical(top: Radius.circular(16)),
+        ),
+        child: Obx(() => ListView(
+          controller: scrollController,
+          padding: const EdgeInsets.all(16),
+          children: [
+            Text(
+              'Raised hands (${ctrl.raised.length})',
+              style: const TextStyle(fontWeight: FontWeight.w600),
+            ),
+            const SizedBox(height: 8),
+            for (final p in ctrl.raised)
+              ListTile(
+                leading: const Text('✋', style: TextStyle(fontSize: 20)),
+                title: Text(p.name),
+                trailing: Text(
+                  '${DateTime.now().difference(p.raisedAt).inSeconds}s ago',
+                  style: const TextStyle(color: Colors.grey),
+                ),
+              ),
+          ],
+        )),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Wiring to the call session
+
+```dart
+@override
+void initState() {
+  super.initState();
+  Get.put(RaiseHandController());
+
+  // Attach to the call session — the controller IS the listener
+  final ctrl = Get.find<RaiseHandController>();
+  CometChatCalls.addCallEventListener('raise-hand', ctrl);
+}
+
+@override
+void dispose() {
+  CometChatCalls.removeCallEventListener('raise-hand');
+  Get.delete<RaiseHandController>();
+  super.dispose();
+}
+```
+
+Use a STABLE listener ID ('raise-hand'). Changing IDs across remounts orphans listeners — duplicate events fire for each.
+
+---
+
+## Anti-patterns
+
+Web sister reference rules apply, plus Flutter V5-specific:
+
+1. **Forgetting `Get.delete<RaiseHandController>()` on dispose.** GetX retains the controller across navigation — listeners survive past the call view, fire stale events.
+2. **`Get.put(RaiseHandController(), permanent: true)` for the call.** Lifetime is too long; controller survives logout. Use scoped `Get.put` without permanent.
+3. **Skipping `Semantics` wrapper on the button.** TalkBack reads the GestureDetector as untyped — bad a11y.
+4. **`Obx` rebuilding the entire widget tree** when only one `.obs` field changes. Wrap minimally — the `Obx` should hug only the reactive part.
+5. **DraggableScrollableSheet without `initialChildSize` < `minChildSize`** — sheet pops above the screen on render, looks broken.
+
+---
+
+## Verification checklist
+
+- [ ] `RaiseHandController` is a `GetxController`
+- [ ] `localRaised` and `raised` are `.obs` reactive
+- [ ] `Obx` wraps only reactive parts of the UI
+- [ ] `Semantics` wrapper on toggle button with `button: true, selected:, label:`
+- [ ] `SemanticsService.announce` on toggle
+- [ ] Stable listener ID for `addCallEventListener` / `removeCallEventListener`
+- [ ] `Get.delete<RaiseHandController>()` in `dispose()`
+- [ ] `hideRaiseHandButton: true` in CallSettings if custom UI
+- [ ] Real-device smoke: 3 devices (mix of iOS + Android), raise from 2 → host sees both
+- [ ] TalkBack / VoiceOver announces "Hand raised" / "Hand lowered" on toggle
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/raise-hand.md` — sister reference (UX shape)
+- `cometchat-flutter-v5-calls` SKILL.md — V5 hard rules + GetX scope rules
+- `cometchat-flutter-v6-calls/references/raise-hand.md` — V6 sibling (Bloc-based — different state shape)
+- `cometchat-a11y` — Flutter Semantics + SemanticsService
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/raise-hand

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

@@ -0,0 +1,193 @@
+# Ringing — call signaling with custom UI (Flutter V5 / GetX)
+
+Same SDK shape as web/RN. Flutter-specific deltas: GetX-controlled state, flutter_callkit_incoming for OS-level backgrounded UI, just_audio for foreground ringtone.
+
+**Read first:** `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules.
+
+---
+
+## SDK API + GetX controller
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+class CallSignalingController extends GetxController implements CallListener {
+  final incoming = Rx<Call?>(null);
+  final outgoing = Rx<Call?>(null);
+  final activeSessionId = Rx<String?>(null);
+
+  static const _listenerId = 'app';
+
+  @override
+  void onInit() {
+    super.onInit();
+    CometChat.addCallListener(_listenerId, this);
+  }
+
+  @override
+  void onIncomingCallReceived(Call call) {
+    incoming.value = call;
+  }
+
+  @override
+  void onOutgoingCallAccepted(Call call) {
+    outgoing.value = null;
+    activeSessionId.value = call.sessionId;
+  }
+
+  @override
+  void onOutgoingCallRejected(Call call) {
+    outgoing.value = null;
+  }
+
+  @override
+  void onIncomingCallCancelled(Call call) {
+    incoming.value = null;
+  }
+
+  @override
+  void onCallEndedMessageReceived(Call call) {
+    incoming.value = null;
+    outgoing.value = null;
+    activeSessionId.value = null;
+  }
+
+  Future<void> initiate(String receiverUid, {String type = 'video'}) async {
+    final call = Call(
+      receiverUid: receiverUid,
+      callType: type == 'video' ? CometChatCallType.video : CometChatCallType.audio,
+      receiverType: CometChatReceiverType.user,
+    );
+    final result = await CometChat.initiateCall(call: call);
+    if (result is Call) outgoing.value = result;
+  }
+
+  Future<void> accept(Call call) async {
+    final result = await CometChat.acceptCall(sessionId: call.sessionId!);
+    if (result is Call) {
+      incoming.value = null;
+      activeSessionId.value = result.sessionId;
+    }
+  }
+
+  Future<void> reject(Call call) async {
+    await CometChat.rejectCall(
+      sessionId: call.sessionId!,
+      status: CallStatus.rejected,
+    );
+    incoming.value = null;
+  }
+
+  @override
+  void onClose() {
+    CometChat.removeCallListener(_listenerId);
+    super.onClose();
+  }
+}
+```
+
+Initialize at app start via `Get.put(CallSignalingController(), permanent: true);` so the listener survives navigation.
+
+---
+
+## Incoming-call overlay
+
+```dart
+class IncomingCallOverlay extends StatelessWidget {
+  const IncomingCallOverlay({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final ctrl = Get.find<CallSignalingController>();
+
+    return Obx(() {
+      final call = ctrl.incoming.value;
+      if (call == null) return const SizedBox.shrink();
+
+      return Material(
+        color: Colors.black.withOpacity(0.85),
+        child: Center(
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              CircleAvatar(
+                radius: 60,
+                backgroundImage: NetworkImage(call.callInitiator?.avatar ?? ''),
+              ),
+              const SizedBox(height: 16),
+              Text(
+                call.callInitiator?.name ?? 'Unknown',
+                style: const TextStyle(color: Colors.white, fontSize: 24),
+              ),
+              Text('Incoming ${call.type} call', style: const TextStyle(color: Colors.white70)),
+              const SizedBox(height: 32),
+              Row(
+                mainAxisAlignment: MainAxisAlignment.center,
+                children: [
+                  Semantics(
+                    label: 'Decline call',
+                    button: true,
+                    child: FloatingActionButton(
+                      backgroundColor: Colors.red,
+                      onPressed: () => ctrl.reject(call),
+                      child: const Icon(Icons.call_end),
+                    ),
+                  ),
+                  const SizedBox(width: 32),
+                  Semantics(
+                    label: 'Accept call',
+                    button: true,
+                    child: FloatingActionButton(
+                      backgroundColor: Colors.green,
+                      onPressed: () => ctrl.accept(call),
+                      child: const Icon(Icons.call),
+                    ),
+                  ),
+                ],
+              ),
+            ],
+          ),
+        ),
+      );
+    });
+  }
+}
+```
+
+Wrap above the navigator (typically in `MaterialApp.builder` or as a sibling Stack item) so it surfaces over any route.
+
+---
+
+## Backgrounded ring — flutter_callkit_incoming + push (mandatory)
+
+GetX listeners only fire while the app is alive. For backgrounded/killed ring, server fires push (APNs PushKit on iOS, FCM data-message on Android) → `flutter_callkit_incoming` shows OS-level UI. See `cometchat-flutter-v5-calls/references/server-push-bridge.md`.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Flutter-specific:
+
+1. **`Get.put` without `permanent: true`.** Controller disposed on route change → listener gone → backgrounded calls miss.
+2. **`StatefulWidget` with `setState` instead of `Obx`.** Rx values won't trigger rebuild without `Obx` wrapper.
+3. **JS-style ringtone via `audioplayers` during a CallKit ring.** Both play at once.
+
+---
+
+## Verification checklist
+
+- [ ] `Get.put(CallSignalingController(), permanent: true)` at app start
+- [ ] `IncomingCallOverlay` mounted in `MaterialApp.builder`
+- [ ] `removeCallListener` in `onClose`
+- [ ] `flutter_callkit_incoming` wired for backgrounded ring
+- [ ] Real-device smoke (iOS + Android): foreground, backgrounded, killed ring all surface UI
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/ringing-integration.md` — canonical
+- `cometchat-flutter-v5-calls/SKILL.md` — Flutter calls architecture
+- `cometchat-flutter-v5-calls/references/server-push-bridge.md` — backgrounded ring
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/ringing

package/skills/cometchat-flutter-v5-calls/references/server-push-bridge.md

@@ -0,0 +1,101 @@
+# Server-side push routing for Flutter V5 (iOS PushKit + Android FCM)
+
+Same server architecture as React Native — your server uses the iOS APNs PushKit canonical for iPhones and the Android FCM HTTP v1 canonical for Android. Flutter-specific changes are in token registration on the client.
+
+**Canonical docs:**
+- iOS: `cometchat-ios-calls/references/server-apns-pushkit.md`
+- Android: `cometchat-android-v5-calls/references/server-fcm-voip.md`
+
+---
+
+## Dependencies
+
+```yaml
+dependencies:
+  flutter_callkit_incoming: ^2.0.4
+  flutter_voip_pushkit: ^0.2.1
+  firebase_messaging: ^15.0.0
+```
+
+---
+
+## Token registration (Flutter client)
+
+```dart
+import 'dart:io';
+import 'package:flutter_voip_pushkit/flutter_voip_pushkit.dart';
+import 'package:firebase_messaging/firebase_messaging.dart';
+
+class CallPushService {
+  Future<void> registerCallTokens(String userUid) async {
+    if (Platform.isIOS) {
+      final voip = FlutterVoipPushKit();
+      voip.onTokenRefresh.listen((token) async {
+        await api.registerCallToken(
+          uid: userUid,
+          platform: 'ios-voip',
+          token: token,
+        );
+      });
+      voip.onPushNotification.listen((payload) {
+        // flutter_callkit_incoming surfaces the OS UI from here
+      });
+      // Trigger token registration
+      await voip.configure();
+    } else if (Platform.isAndroid) {
+      final messaging = FirebaseMessaging.instance;
+      await messaging.requestPermission();
+      final token = await messaging.getToken();
+      if (token != null) {
+        await api.registerCallToken(
+          uid: userUid,
+          platform: 'android-fcm',
+          token: token,
+        );
+      }
+      messaging.onTokenRefresh.listen((newToken) async {
+        await api.registerCallToken(
+          uid: userUid,
+          platform: 'android-fcm',
+          token: newToken,
+        );
+      });
+    }
+  }
+}
+```
+
+---
+
+## Server-side: same as RN
+
+Identical webhook + dispatcher to RN — the platform-specific server templates do all the work. See `cometchat-native-calls/references/server-push-bridge.md` for the dispatcher code.
+
+---
+
+## Anti-patterns
+
+RN sister rules apply, plus Flutter-specific:
+
+1. **Calling `voip.configure()` before login.** Same problem as RN — register AFTER CometChat login.
+2. **Forgetting `firebase_messaging` background isolate setup.** Android background pushes when the app is killed need `FirebaseMessaging.onBackgroundMessage(handler)` registered in `main.dart` before `runApp`.
+3. **Skipping `flutter_callkit_incoming.showCallkitIncoming` in the push handler.** Without this, Flutter doesn't surface the OS-level call UI even though the push arrived.
+
+---
+
+## Verification checklist
+
+- [ ] iOS: `FlutterVoipPushKit.configure()` + onTokenRefresh listener
+- [ ] Android: `FirebaseMessaging.instance.getToken()` + onTokenRefresh
+- [ ] Background isolate handler for Android (`onBackgroundMessage`)
+- [ ] Server has both APNs + FCM dispatchers
+- [ ] Real-device smoke: both iOS and Android ring when caller dials
+
+---
+
+## Pointers
+
+- `cometchat-ios-calls/references/server-apns-pushkit.md` — iOS canonical
+- `cometchat-android-v5-calls/references/server-fcm-voip.md` — Android canonical
+- `cometchat-native-calls/references/server-push-bridge.md` — RN sister (same dispatcher pattern)
+- `cometchat-flutter-v5-calls` SKILL.md — Flutter calls architecture

package/skills/cometchat-flutter-v5-calls/references/share-invite.md

@@ -0,0 +1,142 @@
+# Share invite on Flutter V5 (GetX)
+
+Same SDK API. Flutter-specific: `share_plus` package wraps both iOS UIActivityViewController and Android Intent.ACTION_SEND under one cross-platform API.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/share-invite
+**Read first:** `cometchat-react-calls/references/share-invite.md` — deep-link rule, dialog UX.
+
+---
+
+## Dependencies
+
+```yaml
+dependencies:
+  share_plus: ^10.0.0
+  uni_links: ^0.5.1   # for deep-link handling
+```
+
+---
+
+## Hard rule: deep-link routing
+
+Configure both platforms:
+
+**iOS** (`ios/Runner/Info.plist`):
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array><string>applinks:yourapp.com</string></array>
+```
+Plus apple-app-site-association on your domain (see iOS reference).
+
+**Android** (`android/app/src/main/AndroidManifest.xml`):
+```xml
+<activity android:name=".MainActivity" ...>
+  <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="/call" />
+  </intent-filter>
+</activity>
+```
+
+Plus the corresponding `assetlinks.json` on your domain.
+
+Handle in app:
+```dart
+void initDeepLinks() {
+  uriLinkStream.listen((Uri? uri) {
+    if (uri == null) return;
+    if (uri.pathSegments.length >= 2 && uri.pathSegments[0] == 'call') {
+      final sessionId = uri.pathSegments[1];
+      Get.toNamed('/call/$sessionId');
+    }
+  });
+}
+```
+
+---
+
+## SDK API
+
+```dart
+final settings = CallSettingsBuilder()
+  ..setHideShareInviteButton(false);
+
+@override
+void onShareInviteButtonClicked() {
+  Get.find<ShareInviteController>().share(sessionId);
+}
+```
+
+---
+
+## share_plus
+
+```dart
+import 'package:share_plus/share_plus.dart';
+
+class ShareInviteController extends GetxController {
+  Future<void> share(String sessionId) async {
+    final url = 'https://yourapp.com/call/$sessionId';
+    final result = await Share.share(
+      "I'm on a call — tap to join.\n$url",
+      subject: 'Join my call',  // Android: title; iOS: ignored
+    );
+
+    if (result.status == ShareResultStatus.success) {
+      // logged + maybe haptic feedback
+    }
+    // dismissed/unavailable: silent
+  }
+}
+```
+
+`Share.share` opens iOS UIActivityViewController on iOS and the Android chooser on Android. The same call works on both.
+
+---
+
+## iPad popover anchor
+
+`share_plus` requires a source rect on iPad:
+
+```dart
+final box = context.findRenderObject() as RenderBox?;
+await Share.share(
+  text,
+  sharePositionOrigin: box != null ? box.localToGlobal(Offset.zero) & box.size : null,
+);
+```
+
+Pass `sharePositionOrigin` from the button's render box. Without it, share sheet crashes on iPad.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus Flutter-specific:
+
+1. **Calling `Share.share` without iPad anchor.** Crash on iPad in production.
+2. **Hard-coding URL.** Use `dotenv` or `--dart-define=APP_URL=...`.
+3. **No deep-link config for both platforms.** Only iOS works (or only Android), not both — partial UX.
+
+---
+
+## Verification checklist
+
+- [ ] `share_plus` installed
+- [ ] Associated Domains (iOS) + auto-verified app links (Android) configured
+- [ ] `assetlinks.json` + `apple-app-site-association` hosted
+- [ ] `Share.share` called with `sharePositionOrigin` for iPad
+- [ ] App URL via env, not hard-coded
+- [ ] Real-device smoke: share via Messages on iOS, WhatsApp on Android → opens app
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/share-invite.md` — sister
+- `cometchat-flutter-v5-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/share-invite

package/skills/cometchat-flutter-v5-conversations/SKILL.md

@@ -3,7 +3,7 @@ name: cometchat-flutter-v5-conversations
 description: "Use when working with CometChat Flutter UIKit v5 conversation list component. Triggers on CometChatConversations, conversation list, recent chats."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v5-core/SKILL.md

@@ -3,7 +3,7 @@ name: cometchat-flutter-v5-core
 description: "Use when writing any code that uses CometChat Flutter UIKit v5 (cometchat_chat_uikit v5.2.14, cometchat_calls_uikit v5.0.15, cometchat_uikit_shared v5.2.3). Contains hard rules that prevent silent failures."
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3; cometchat_sdk ^4.1.2; get ^4.6.5"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"