@cometchat/skills 3.0.0 → 4.0.0

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

@@ -0,0 +1,192 @@
+---
+name: cometchat-flutter-v5-calls
+description: "Use when working with CometChat Flutter UIKit v5 call components. Triggers on CometChatCallButtons, CometChatIncomingCall, CometChatOutgoingCall, CometChatOngoingCall, CometChatCallLogs, calling."
+license: "MIT"
+compatibility: "cometchat_calls_uikit ^5.0.15; cometchat_calls_sdk ^4.2.2; cometchat_sdk ^4.1.2"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 calls voice video incoming outgoing ongoing logs"
+---
+
+# CometChat Flutter UIKit v5 — Calls
+
+Components and utilities for voice/video calling.
+
+## Package Structure
+
+Calls are in a **separate package**: `cometchat_calls_uikit`.
+
+```yaml
+dependencies:
+  cometchat_calls_uikit: ^5.0.15
+```
+
+Import everything from:
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+```
+
+This re-exports `cometchat_uikit_shared`, `cometchat_sdk`, and `cometchat_calls_sdk`.
+
+## Rule: CALLS_INIT_ORDER
+
+Chat SDK must be initialized BEFORE Calls SDK. The calling extension handles this automatically when configured via `UIKitSettingsBuilder.callingExtension`.
+
+```dart
+// ✅ CORRECT — enable calling via UIKitSettings
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      ..authKey = 'AUTH_KEY'
+      ..subscriptionType = CometChatSubscriptionType.allUsers
+      ..callingExtension = CometChatCallingExtension())
+    .build();
+
+CometChatUIKit.init(uiKitSettings: settings);
+```
+
+`CometChatCallingExtension` extends `ExtensionsDataSource` and uses `ChatConfigurator.enable()` to register the calling decorator.
+
+## Rule: CALL_NAVIGATION_CONTEXT
+
+`CallNavigationContext.navigatorKey` must be set on `MaterialApp` for call overlays to navigate:
+
+```dart
+MaterialApp(
+  navigatorKey: CallNavigationContext.navigatorKey,
+)
+```
+
+## CometChatCallButtons
+
+Voice and video call buttons for a user or group.
+
+```dart
+CometChatCallButtons(user: user)
+CometChatCallButtons(group: group, hideVoiceCallButton: true)
+```
+
+Key props: `user`, `group`, `callButtonsStyle`, `hideVoiceCallButton`, `hideVideoCallButton`, `outgoingCallConfiguration`, `callSettingsBuilder`, `onError`.
+
+## CometChatCallLogs
+
+Call history list.
+
+```dart
+CometChatCallLogs(
+  onItemClick: (callLog) {
+    // CometChatCallLogDetails is NOT a UIKit export — copy the
+    // sample-app pattern from `sample_app/lib/call_log_details/` into
+    // your own project and route to it here.
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => YourCallLogDetailsScreen(callLog: callLog),
+    ));
+  },
+)
+```
+
+Key props: `callLogsRequestBuilder`, `callLogsStyle`, `onItemClick`, `listItemView`, `subTitleView`, `trailingView`, `onError`.
+
+## CometChatIncomingCall / CometChatOutgoingCall / CometChatOngoingCall
+
+These are typically managed automatically by `CometChatCallingExtension`. Manual usage is rare.
+
+- `CometChatIncomingCall(call: call, onAccept: (BuildContext, Call)? ..., onDecline: (BuildContext, Call)? ...)` — callbacks take `(BuildContext, Call)`, NOT `(Call)` alone.
+- `CometChatOutgoingCall(call: returnedCall, user: user OR group: group, onCancelled: (BuildContext, Call)? ...)` — takes the active `Call` object plus the `User` or `Group` it's directed at. The `call:` param holds the result of `CometChatUIKitCalls.initiateCall(...)`. Callbacks are `(BuildContext, Call)?`, NOT `(Call)?` alone.
+- `CometChatOngoingCall(callSettingsBuilder: ..., sessionId: ...)`
+
+## Call Flow — Outgoing
+
+1. User taps call button → `CometChatUIKitCalls.initiateCall(call)`
+2. `CometChatOutgoingCall` screen pushed
+3. Recipient accepts → `CometChatOngoingCall` replaces outgoing
+4. Call ends → screens pop back
+
+## Call Flow — Incoming
+
+1. `CometChatCallingExtension` listens via SDK listener
+2. `CometChatIncomingCall` overlay displayed via `CallNavigationContext.navigatorKey`
+3. Accept → `CometChatUIKitCalls.acceptCall(sessionId)` → `CometChatOngoingCall`
+4. Decline → `CometChatUIKitCalls.rejectCall(sessionId, status)`
+
+## Incoming Call Handling (Global)
+
+Handle incoming calls at the app level (dashboard/home), not per-screen:
+
+```dart
+class _DashboardState extends State<Dashboard>
+    with CallListener, CometChatCallEventListener {
+
+  @override
+  void initState() {
+    super.initState();
+    _listenerId = 'calls_${DateTime.now().millisecondsSinceEpoch}';
+    CometChat.addCallListener(_listenerId, this);
+    CometChatCallEvents.addCallEventsListener(_listenerId, this);
+  }
+
+  @override
+  void dispose() {
+    CometChat.removeCallListener(_listenerId);
+    CometChatCallEvents.removeCallEventsListener(_listenerId);
+    super.dispose();
+  }
+
+  @override
+  void onIncomingCallReceived(Call call) {
+    // Handle incoming call globally
+  }
+}
+```
+
+## Permissions
+
+Request camera and microphone permissions before calls:
+
+```dart
+await [Permission.camera, Permission.microphone].request();
+```
+
+## Golden Path — Enable Calling
+
+```dart
+// 1. Configure calling extension
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      ..authKey = 'AUTH_KEY'
+      ..subscriptionType = CometChatSubscriptionType.allUsers
+      ..callingExtension = CometChatCallingExtension())
+    .build();
+
+// 2. Init
+CometChatUIKit.init(uiKitSettings: settings);
+
+// 3. Set navigator key
+MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)
+
+// 4. Call buttons appear automatically in CometChatMessageHeader
+```
+
+## Anti-Patterns
+
+```dart
+// ❌ WRONG — forgetting navigatorKey
+MaterialApp(/* missing navigatorKey */)
+
+// ❌ WRONG — not enabling calling extension
+UIKitSettingsBuilder()..appId = 'APP_ID'..region = 'us'
+// Missing: ..callingExtension = CometChatCallingExtension()
+
+// ❌ WRONG — handling incoming calls per-screen instead of globally
+```
+
+## Checklist — Calls
+
+- [ ] `CometChatCallingExtension()` set on `UIKitSettingsBuilder.callingExtension`
+- [ ] `CallNavigationContext.navigatorKey` set on `MaterialApp.navigatorKey`
+- [ ] Incoming call handling is global (dashboard level)
+- [ ] Camera/microphone permissions requested
+- [ ] Import from `package:cometchat_calls_uikit/cometchat_calls_uikit.dart`

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

@@ -0,0 +1,117 @@
+---
+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"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 conversations list recent chats"
+---
+
+# CometChat Flutter UIKit v5 — Conversations
+
+The `CometChatConversations` component displays a list of recent conversations.
+
+## Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `conversationsRequestBuilder` | `ConversationsRequestBuilder?` | — | Custom fetch builder |
+| `conversationsStyle` | `CometChatConversationsStyle` | `const CometChatConversationsStyle()` | Visual styling |
+| `onItemTap` | `Function(Conversation)?` | — | Tap callback (**no BuildContext**) |
+| `onItemLongPress` | `Function(Conversation)?` | — | Long press callback |
+| `subtitleView` | `Widget? Function(BuildContext, Conversation)?` | — | Custom subtitle |
+| `listItemView` | `Widget Function(Conversation)?` | — | Custom list item (replaces the whole row) |
+| `leadingView` | `Widget? Function(BuildContext, Conversation)?` | — | Custom leading widget (avatar slot) |
+| `titleView` | `Widget? Function(BuildContext, Conversation)?` | — | Custom title widget |
+| `trailingView` | `Widget? Function(Conversation)?` | — | Custom trailing widget (single-arg — asymmetric with the other slots) |
+| `title` | `String?` | — | List title |
+| `showBackButton` | `bool` | `false` | Show back button |
+| `onBack` | `VoidCallback?` | — | Back button callback |
+| `hideAppbar` | `bool?` | `false` | Hide app bar |
+| `appBarOptions` | `List<Widget>?` | — | App bar trailing widgets |
+| `usersStatusVisibility` | `bool?` | `true` | Show online status |
+| `receiptsVisibility` | `bool?` | `true` | Show read receipts |
+| `textFormatters` | `List<CometChatTextFormatter>?` | — | Text formatters for subtitles |
+| `controllerTag` | `String?` | — | Custom GetX controller tag |
+| `hideSearch` | `bool?` | — | Hide search bar |
+| `searchReadOnly` | `bool` | `false` | Read-only search |
+| `onSearchTap` | `GestureTapCallback?` | — | Search tap callback |
+| `deleteConversationOptionVisibility` | `bool?` | `true` | Show delete option |
+| `loadingStateView` | `WidgetBuilder?` | — | Custom loading state |
+| `emptyStateView` | `WidgetBuilder?` | — | Custom empty state |
+| `errorStateView` | `WidgetBuilder?` | — | Custom error state |
+| `setOptions` | `Function?` | — | Replace long-press options |
+| `addOptions` | `Function?` | — | Add to long-press options |
+
+## Basic Usage
+
+```dart
+CometChatConversations(
+  onItemTap: (conversation) {
+    User? user;
+    Group? group;
+    if (conversation.conversationWith is User) {
+      user = conversation.conversationWith as User;
+    } else {
+      group = conversation.conversationWith as Group;
+    }
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(user: user, group: group),
+    ));
+  },
+)
+```
+
+## Custom Request Builder
+
+```dart
+CometChatConversations(
+  conversationsRequestBuilder: ConversationsRequestBuilder()
+    ..limit = 30
+    ..conversationType = ConversationType.user,
+)
+```
+
+## Internal Architecture (GetX)
+
+The component creates `CometChatConversationsController` via `Get.put()` in `initState()` and deletes it in `dispose()` (unless `controllerTag` is provided externally).
+
+Theme values are cached in `didChangeDependencies()` (unconditionally, no flag):
+```dart
+@override
+void didChangeDependencies() {
+  typography = CometChatThemeHelper.getTypography(context);
+  colorPalette = CometChatThemeHelper.getColorPalette(context);
+  spacing = CometChatThemeHelper.getSpacing(context);
+  style = CometChatThemeHelper.getTheme<CometChatConversationsStyle>(
+      context: context, defaultTheme: CometChatConversationsStyle.of)
+    .merge(widget.conversationsStyle);
+  super.didChangeDependencies();
+}
+```
+
+## Anti-Patterns
+
+```dart
+// ❌ WRONG — trying to access controller before component mounts
+final controller = Get.find<CometChatConversationsController>();
+
+// ❌ WRONG — manually creating controller outside the widget
+Get.put(CometChatConversationsController(...));
+
+// ❌ WRONG — not extracting User/Group from conversation
+onItemTap: (conversation) {
+  Navigator.push(context, MaterialPageRoute(
+    builder: (_) => MessagesScreen(user: conversation.conversationWith), // Type error
+  ));
+}
+```
+
+## Checklist — Conversations
+
+- [ ] `onItemTap` extracts `User`/`Group` from `conversation.conversationWith` with type check
+- [ ] Navigation to messages screen passes extracted `user` or `group`
+- [ ] Let the widget manage its own GetX controller lifecycle

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

@@ -0,0 +1,221 @@
+---
+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"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 core rules init login logout lifecycle getx"
+---
+
+# CometChat Flutter UIKit v5 — Core Rules
+
+Non-negotiable constraints for all CometChat UIKit v5 code. Violating these causes silent failures or crashes.
+
+## Key v5 Architecture Facts
+
+- State management: **GetX** (GetBuilder, GetxController, Get.put, Get.find, Get.delete)
+- Separate packages: `cometchat_chat_uikit` + `cometchat_calls_uikit` + `cometchat_uikit_shared`
+- SDK: `cometchat_sdk ^4.1.2` + `cometchat_calls_sdk ^4.2.2`
+- **Imports — two barrels.** For chat-only projects: `package:cometchat_chat_uikit/cometchat_chat_uikit.dart`. For projects that also need voice/video calling: ADD `package:cometchat_calls_uikit/cometchat_calls_uikit.dart` as a SECOND import — the calls barrel re-exports shared + SDK only and does NOT re-export `cometchat_chat_uikit`. Chat widgets like `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer` are reachable only through the chat barrel.
+- `CometChatUIKit.login(uid)` takes a **String** directly (not an object)
+- No ServiceLocator pattern — controllers are created via `Get.put()` internally
+- Style classes use `ThemeExtension` with `merge()` pattern
+
+## Rule: INIT_FIRST
+
+`CometChatUIKit.init()` must complete before any login, component usage, or SDK call.
+
+```dart
+// ✅ CORRECT
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      ..authKey = 'AUTH_KEY'
+      ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) => debugPrint('Init done'),
+  onError: (e) => debugPrint('Init failed: ${e.message}'),
+);
+
+// ❌ WRONG — login before init completes
+CometChatUIKit.init(uiKitSettings: settings);
+CometChatUIKit.login('uid'); // Race condition
+```
+
+## Rule: AUTH_CHECK_AFTER_INIT
+
+After `CometChatUIKit.init()` completes, the static field `CometChatUIKit.loggedInUser` is populated if a cached session exists (init internally calls `getLoggedInUser()`). You can check it synchronously in `onSuccess`, or use `CometChatUIKit.getLoggedInUser()` for an explicit async check.
+
+```dart
+// ✅ CORRECT — synchronous check after init
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) {
+    final hasUser = CometChatUIKit.loggedInUser != null;
+    // Route to home or login
+  },
+);
+
+// ✅ ALSO CORRECT — explicit async check (used by master app)
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) async {
+    final user = await CometChatUIKit.getLoggedInUser();
+    if (user != null) {
+      await CometChatUIKit.login(user.uid, onSuccess: ...);
+    }
+  },
+);
+```
+
+Note: `CometChatUIKit.login()` handles re-login gracefully — if the user is already logged in with the same UID, it returns the cached user without hitting the server.
+
+## Rule: LISTENER_LIFECYCLE
+
+SDK listeners MUST be registered with a unique ID in `initState()` (or GetxController `onInit()`) and removed in `dispose()` (or `onClose()`).
+
+```dart
+// ✅ CORRECT
+class _MyScreenState extends State<MyScreen> with MessageListener {
+  late final String _listenerId;
+
+  @override
+  void initState() {
+    super.initState();
+    _listenerId = 'my_screen_${DateTime.now().millisecondsSinceEpoch}';
+    CometChat.addMessageListener(_listenerId, this);
+  }
+
+  @override
+  void dispose() {
+    CometChat.removeMessageListener(_listenerId);
+    super.dispose();
+  }
+}
+
+// ❌ WRONG — hardcoded ID causes collisions; missing dispose removal
+CometChat.addMessageListener('messages', this); // Collision!
+```
+
+## Rule: THEME_CACHE
+
+Cache theme values in `didChangeDependencies()` — unconditionally, no flag needed. Never call `CometChatThemeHelper.getColorPalette(context)` in `build()`.
+
+`getColorPalette()` creates a new `CometChatColorPalette` object every call, resolving each token individually via `Theme.of(context)`. During keyboard animation, `MediaQuery` changes trigger rebuilds, making this expensive in `build()`.
+
+```dart
+// ✅ CORRECT — matches actual package pattern (no flag)
+@override
+void didChangeDependencies() {
+  super.didChangeDependencies();
+  colorPalette = CometChatThemeHelper.getColorPalette(context);
+  spacing = CometChatThemeHelper.getSpacing(context);
+  typography = CometChatThemeHelper.getTypography(context);
+}
+
+// ❌ WRONG — lookup in build causes jank
+@override
+Widget build(BuildContext context) {
+  final colors = CometChatThemeHelper.getColorPalette(context); // Expensive!
+  return Container(color: colors.primary);
+}
+```
+
+Do NOT use a `_themeInitialized` flag — it prevents theme updates when the system switches between light/dark mode.
+
+## Rule: SUBSCRIPTION_TYPE_REQUIRED
+
+Omitting `subscriptionType` in `UIKitSettingsBuilder` silently disables all presence events (online/offline, typing indicators). No error is thrown.
+
+```dart
+// ✅ CORRECT
+UIKitSettingsBuilder()
+  ..subscriptionType = CometChatSubscriptionType.allUsers
+```
+
+## Rule: REGION_LOWERCASE
+
+Region must be a lowercase string: `'us'`, `'eu'`, or `'in'`.
+
+## Rule: MUID_PRESERVATION
+
+When handling `ccMessageSent` events, compare by `muid` first, then `id` — the SDK may return an empty `muid` in the success callback.
+
+## Pattern: Callback → Async Bridge (Completer)
+
+```dart
+import 'dart:async';
+
+Future<bool> initAsync(UIKitSettings settings) {
+  final completer = Completer<bool>();
+  CometChatUIKit.init(
+    uiKitSettings: settings,
+    onSuccess: (_) => completer.complete(true),
+    onError: (e) => completer.complete(false),
+  );
+  return completer.future;
+}
+```
+
+## v5 Component Architecture Pattern (GetX)
+
+```
+{component}/
+├── cometchat_{component}.dart              # StatefulWidget
+├── cometchat_{component}_controller.dart   # extends GetxController
+├── cometchat_{component}_style.dart        # ThemeExtension with merge()
+└── {component}_builder_protocol.dart       # Request builder protocol
+```
+
+Internal lifecycle:
+```dart
+@override
+void initState() {
+  super.initState();
+  tag = widget.controllerTag ?? 'default_tag_${DateTime.now().millisecondsSinceEpoch}';
+  controller = Get.put<Controller>(Controller(...), tag: tag);
+}
+
+@override
+void dispose() {
+  if (widget.controllerTag == null) {
+    Get.delete<Controller>(tag: tag);
+  }
+  super.dispose();
+}
+```
+
+## Android Build Requirements
+
+- `android.useAndroidX=true` and `android.enableJetifier=true` in `gradle.properties`
+- `minSdk 26` in `android/app/build.gradle`
+- ProGuard: `-keep class com.cometchat.** { *; }` and `-keep interface com.cometchat.** { *; }`
+
+## Top 10 Error Debugging
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Authentication null" | `CometChatUIKit.init()` not called | Call init before login/components |
+| "APP ID null" | appId not set in UIKitSettingsBuilder | Set `..appId = 'YOUR_APP_ID'` |
+| No typing indicators / presence | `subscriptionType` not set | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |
+| Theme jank during keyboard | Theme looked up in `build()` | Cache in `didChangeDependencies()` |
+| Listener leak / duplicate events | Listener not removed in `dispose()` | Always remove with same ID |
+| GetX controller not found | Using `Get.find()` before `Get.put()` | Let UIKit components manage their own controllers |
+| Region error | Uppercase region string | Use lowercase: 'us', 'eu', 'in' |
+| Release build crash | Missing ProGuard keep rules | Add `-keep class com.cometchat.** { *; }` |
+
+## Checklist — Every CometChat v5 Screen
+
+- [ ] `CometChatUIKit.init()` called before any usage
+- [ ] `subscriptionType` set in UIKitSettingsBuilder
+- [ ] `region` is lowercase
+- [ ] Theme cached in `didChangeDependencies()`, not `build()`
+- [ ] SDK listeners registered with unique ID, removed in `dispose()`
+- [ ] Colors from `CometChatThemeHelper`, never hardcoded
+- [ ] Imports: `package:cometchat_chat_uikit/cometchat_chat_uikit.dart` always; ADD `package:cometchat_calls_uikit/cometchat_calls_uikit.dart` if you use voice/video