@cometchat/skills 3.0.0 → 4.0.0

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

@@ -0,0 +1,129 @@
+---
+name: cometchat-flutter-v5-troubleshooting
+description: "Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 troubleshooting debug errors fix"
+---
+
+# CometChat Flutter UIKit v5 — Troubleshooting
+
+Symptom-to-cause lookup and verification checks.
+
+## Init / Login Issues
+
+| 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'` |
+| Login hangs silently | `init()` hasn't completed yet | Await init completion via `onSuccess` before calling login |
+| "ERR_INVALID_REGION" | Uppercase region | Use lowercase: `'us'`, `'eu'`, `'in'` |
+| Login succeeds but no messages load | `subscriptionType` not set | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |
+
+## UI / Layout Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Theme jank during keyboard animation | `CometChatThemeHelper.getColorPalette(context)` called in `build()` | Cache in `didChangeDependencies()` |
+| Components don't reflect theme changes | Using `_themeInitialized` flag | Remove flag — cache unconditionally in `didChangeDependencies()` |
+| Hardcoded colors don't match dark mode | Using `Color(0xFF...)` instead of theme tokens | Use `colorPalette.primary`, `colorPalette.textPrimary`, etc. |
+| `colorPalette.white` doesn't change in dark mode | `white`/`black`/`transparent` are NOT brightness-aware | Use `colorPalette.neutral50` for brightness-aware white |
+
+## GetX Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "GetX controller not found" | Using `Get.find()` before `Get.put()` | Let UIKit components manage their own controllers |
+| Controller not disposed | Manually created controller without cleanup | Use `controllerTag` or let widget manage lifecycle |
+| Multiple controller instances | Creating controller outside the widget | Let the widget's `initState()` handle `Get.put()` |
+| `Get.delete()` throws | Deleting controller that was created with `controllerTag` | Only delete if `controllerTag` was null (widget-managed) |
+
+## Listener / Event Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Duplicate events firing | Listener not removed in `dispose()` | Always remove with same ID used to register |
+| Listener ID collision | Hardcoded listener ID string | Use timestamp: `'id_${DateTime.now().millisecondsSinceEpoch}'` |
+| No typing indicators | `subscriptionType` not set | Set `CometChatSubscriptionType.allUsers` |
+| No online/offline status | `subscriptionType` not set | Same fix |
+| `ccMessageSent` not firing | Using `CometChat.sendMessage()` directly | Use `CometChatUIKit.sendTextMessage()` instead |
+| Events fire after screen disposed | Listener not removed | Remove in `dispose()` / `onClose()` |
+
+## Call Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Incoming call overlay doesn't show | `CallNavigationContext.navigatorKey` not set | Set on `MaterialApp.navigatorKey` |
+| Call buttons don't appear | `CometChatCallingExtension` not registered | Set `..callingExtension = CometChatCallingExtension()` on UIKitSettingsBuilder |
+| Call fails silently | Camera/microphone permissions not granted | Request `Permission.camera` and `Permission.microphone` |
+| Incoming calls not handled | Call listener not registered globally | Register `CallListener` + `CometChatCallEventListener` at dashboard level |
+
+## Push Notification Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No push notifications | Token not registered | Call `PNRegistry.registerPNService(token, isFcm, isVoip)` |
+| Notifications after logout | Token not unregistered | Call `PNRegistry.unregisterPNService()` before logout |
+| Duplicate notifications | Foreground notification shown for active conversation | Check `conversationId` match before showing |
+| VoIP call notification doesn't show | Background handler not top-level | Use `@pragma('vm:entry-point')` on top-level function |
+| Tap doesn't navigate | `CallNavigationContext.navigatorKey.currentContext` is null | Ensure `navigatorKey` is set on MaterialApp |
+| iOS VoIP token not registered | Missing VoIP background mode | Enable Voice over IP in Xcode Background Modes |
+
+## Android Build Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Release build crash | Missing ProGuard keep rules | Add `-keep class com.cometchat.** { *; }` |
+| Build fails with minSdk error | minSdk too low | Set `minSdk 26` in `android/app/build.gradle` |
+| AndroidX conflict | Missing AndroidX migration | Set `android.useAndroidX=true` in `gradle.properties` |
+
+## iOS Build Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Camera/mic permission crash | Missing Info.plist entries | Add `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` |
+| Pod install fails | Cocoapods version mismatch | Run `pod repo update` then `pod install` |
+
+## Callback Signature Errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Type error on `CometChatUsers.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, User)?` |
+| Type error on `CometChatGroups.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, Group)?` |
+| Type error on `CometChatConversations.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(Conversation)?` — no BuildContext |
+| Type error on `CometChatGroupMembers.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(GroupMember)?` — no BuildContext |
+
+## v5 vs v6 Drift Detection
+
+If you see any of these in a v5 project, it's a v6 pattern that was accidentally used:
+
+| v6 Pattern (wrong in v5) | v5 Equivalent |
+|--------------------------|---------------|
+| `import 'package:flutter_bloc/flutter_bloc.dart'` | GetX — no BLoC in v5 |
+| `extends Bloc<Event, State>` | `extends GetxController` |
+| `extends Equatable` | Not used in v5 |
+| `ServiceLocator.get<T>()` | `Get.find<T>()` or let widget manage |
+| Single `cometchat_chat_uikit` with calls built-in | Separate `cometchat_calls_uikit` package |
+| Per-widget feature flags only — no `BuilderSettings` | `BuilderSettings`, `BuilderColor`, `BuilderTypography` |
+| `enableCalls: true` + `CallingConfiguration()` on UIKitSettingsBuilder | `..callingExtension = CometChatCallingExtension()` |
+
+## Verify Checklist
+
+Run through this when something isn't working:
+
+- [ ] `CometChatUIKit.init()` completes before any other CometChat call
+- [ ] `subscriptionType` set in UIKitSettingsBuilder
+- [ ] `region` is lowercase
+- [ ] Theme cached in `didChangeDependencies()`, not `build()`
+- [ ] All listeners registered with unique IDs
+- [ ] All listeners removed in `dispose()` / `onClose()`
+- [ ] `CallNavigationContext.navigatorKey` set on MaterialApp
+- [ ] `CometChatCallingExtension()` set if using calls
+- [ ] Push tokens registered after login
+- [ ] Push tokens unregistered before logout
+- [ ] ProGuard rules present for release builds
+- [ ] No v6 imports (`flutter_bloc`, `equatable`, `BlocProvider` / `BlocBuilder`)

package/skills/cometchat-flutter-v5-users-groups/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: cometchat-flutter-v5-users-groups
+description: "Use when working with CometChat Flutter UIKit v5 user and group list components. Triggers on CometChatUsers, CometChatGroups, CometChatGroupMembers, CometChatChangeScope."
+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 users groups members scope contacts"
+---
+
+# CometChat Flutter UIKit v5 — Users & Groups
+
+Components for displaying and managing users, groups, and group members.
+
+## CometChatUsers
+
+Displays a list of users, sorted alphabetically.
+
+### Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `usersRequestBuilder` | `UsersRequestBuilder?` | — | Custom fetch builder |
+| `usersStyle` | `CometChatUsersStyle` | `const CometChatUsersStyle()` | Visual styling |
+| `onItemTap` | `Function(BuildContext, User)?` | — | Tap callback (**includes BuildContext**) |
+| `onItemLongPress` | `Function(BuildContext, User)?` | — | Long press callback |
+| `subtitleView` | `Widget? Function(BuildContext, User)?` | — | Custom subtitle |
+| `title` | `String?` | — | List title |
+| `showBackButton` | `bool` | `true` | Show back button |
+| `hideSearch` | `bool` | `false` | Hide search bar |
+| `selectionMode` | `SelectionMode?` | — | Enable selection mode |
+| `onSelection` | `Function(List<User>?, BuildContext)?` | — | Selection callback |
+| `usersStatusVisibility` | `bool?` | `true` | Show online status |
+| `hideAppbar` | `bool?` | `false` | Hide app bar |
+| `appBarOptions` | `List<Widget> Function(BuildContext)?` | — | App bar trailing widgets |
+| `controllerTag` | `String?` | — | Custom GetX controller tag |
+| `stickyHeaderVisibility` | `bool?` | `false` | Show alphabetical headers |
+
+### Usage
+
+```dart
+CometChatUsers(
+  onItemTap: (context, user) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(user: user),
+    ));
+  },
+)
+
+// With custom request builder
+CometChatUsers(
+  usersRequestBuilder: UsersRequestBuilder()
+    ..limit = 30
+    ..friendsOnly = true,
+)
+
+// Filter by role (e.g., AI agents)
+CometChatUsers(
+  title: "Agents",
+  usersRequestBuilder: UsersRequestBuilder()
+    ..roles = [AIConstants.aiRole],
+  onItemTap: (context, user) { ... },
+)
+```
+
+## CometChatGroups
+
+Displays a list of groups with type indicators.
+
+### Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `groupsRequestBuilder` | `GroupsRequestBuilder?` | — | Custom fetch builder |
+| `groupsStyle` | `CometChatGroupsStyle?` | — | Visual styling |
+| `onItemTap` | `Function(BuildContext, Group)?` | — | Tap callback (**includes BuildContext**) |
+| `onItemLongPress` | `Function(BuildContext, Group)?` | — | Long press callback |
+| `subtitleView` | `Widget? Function(BuildContext, Group)?` | — | Custom subtitle |
+| `title` | `String?` | — | List title |
+| `showBackButton` | `bool` | `true` | Show back button |
+| `hideSearch` | `bool` | `false` | Hide search bar |
+| `selectionMode` | `SelectionMode?` | — | Enable selection mode |
+| `groupTypeVisibility` | `bool` | `true` | Show group type icon |
+| `hideAppbar` | `bool?` | `false` | Hide app bar |
+| `appBarOptions` | `List<Widget> Function(BuildContext)?` | — | App bar trailing widgets |
+| `controllerTag` | `String?` | — | Custom GetX controller tag |
+
+### Usage
+
+```dart
+CometChatGroups(
+  onItemTap: (context, group) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(group: group),
+    ));
+  },
+)
+```
+
+## CometChatGroupMembers
+
+Displays members of a specific group with role indicators.
+
+```dart
+CometChatGroupMembers(
+  group: group,
+  onItemTap: (member) {
+    debugPrint('Tapped: ${member.name}, role: ${member.scope}');
+  },
+)
+```
+
+Key props: `group` (required), `groupMembersRequestBuilder`, `groupMembersStyle`, `subtitleView`, `trailingView`, `onItemTap` (`Function(GroupMember)?` — **no BuildContext**), `selectionMode`, `onSelection`.
+
+## CometChatChangeScope
+
+Widget for changing a group member's scope/role.
+
+```dart
+CometChatChangeScope(group: group, member: member)
+```
+
+## Callback Signature Differences
+
+| Component | `onItemTap` signature |
+|-----------|----------------------|
+| `CometChatConversations` | `Function(Conversation)?` — **no BuildContext** |
+| `CometChatUsers` | `Function(BuildContext, User)?` — **has BuildContext** |
+| `CometChatGroups` | `Function(BuildContext, Group)?` — **has BuildContext** |
+| `CometChatGroupMembers` | `Function(GroupMember)?` — **no BuildContext** |
+
+This is a common source of confusion.
+
+## Anti-Patterns
+
+```dart
+// ❌ WRONG — missing BuildContext in Users/Groups onItemTap
+CometChatUsers(onItemTap: (user) { ... }) // Missing BuildContext!
+
+// ✅ CORRECT
+CometChatUsers(onItemTap: (context, user) { ... })
+CometChatGroups(onItemTap: (context, group) { ... })
+```
+
+## Checklist — Users & Groups
+
+- [ ] `onItemTap` callback signature includes `BuildContext` for Users/Groups
+- [ ] Custom request builders set appropriate limits
+- [ ] Let widgets manage their own GetX controller lifecycle