@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-flutter-v6/SKILL.md

@@ -0,0 +1,445 @@
+---
+name: cometchat-flutter-v6
+description: >
+  Use when building chat with CometChat Flutter UIKit v6 (cometchat_chat_uikit).
+  Triggers on CometChatUIKit, CometChatConversations, CometChatMessageList,
+  CometChatMessageComposer, CometChatMessageHeader, CometChatUsers, CometChatGroups,
+  UIKitSettings, CometChatThemeHelper, CometChatColorPalette, ConversationsBloc,
+  MessageListBloc, CometChatTextBubble, CometChatImageBubble, CometChatMessageBubble,
+  CometChatMentionsFormatter, SliverSpacing, ERR_ALREADY_LOGGED_IN, ERR_INVALID_REGION,
+  authentication null. Also for adding chat to Flutter, customizing bubbles, theming,
+  real-time messages. Use whenever user mentions CometChat or says "chat UI".
+license: "MIT"
+compatibility: "flutter >=2.5.0; dart >=2.17.0; cometchat_chat_uikit 6.0.0-beta2"
+allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter chat uikit messaging conversations bloc clean-architecture"
+---
+
+# CometChat Flutter UIKit v6 — Orchestrator
+
+Entry point skill for the `cometchat_chat_uikit` package. Routes to feature skills based on context.
+
+## Project Detection
+
+Confirm the project uses CometChat UIKit by checking `pubspec.yaml` for:
+```yaml
+dependencies:
+  cometchat_chat_uikit:
+    hosted: https://dart.cloudsmith.io/cometchat/cometchat/
+    version: 6.0.0-beta2
+```
+
+If missing, install via:
+```bash
+dart pub add cometchat_chat_uikit:6.0.0-beta2 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/
+```
+
+Call functionality is built into `cometchat_chat_uikit` — no separate package needed. To use call-specific types, import the calls barrel:
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'; // For call types
+```
+
+## Skill Routing
+
+| User mentions | Route to skill |
+|---------------|---------------|
+| init, login, logout, UIKitSettings, setup, credentials, appId, region | `cometchat-flutter-v6-core` |
+| theme, colors, dark mode, styling, CometChatColorPalette, CometChatSpacing, typography, Style class | `cometchat-flutter-v6-theming` |
+| conversations, conversation list, recent chats, ConversationsBloc | `cometchat-flutter-v6-conversations` |
+| messages, message list, composer, header, keyboard, rich text, bubbles, send message | `cometchat-flutter-v6-messages` |
+| users, groups, group members, contacts, user list | `cometchat-flutter-v6-users-groups` |
+| events, listeners, real-time, typing indicator, online status, receipts, SDK listener | `cometchat-flutter-v6-events` |
+
+## Architecture Overview
+
+The UIKit follows Clean Architecture + BLoC:
+```
+{component}/
+├── bloc/           # BLoC, Events, State (Equatable)
+├── domain/         # Use Cases, Repository interfaces
+├── data/           # Repository impl, DataSources
+├── di/             # ServiceLocator (singleton)
+├── widgets/        # UI components
+└── {component}.dart # Barrel export
+```
+
+All components: conversations, message_list, message_composer, message_header, users, groups, group_members, search, threaded_header, message_information.
+
+## Package Structure
+
+```
+chat_uikit/lib/
+├── cometchat_chat_uikit.dart    # Main barrel export (chat components)
+├── cometchat_calls_uikit.dart   # Calls barrel export
+├── chat_ui/src/                 # Chat components (conversations, messages, users, groups, etc.)
+├── call_ui/src/                 # Call components (incoming, outgoing, ongoing, call_logs)
+└── shared_ui/                   # Shared utilities (theme, events, formatters, models, views)
+```
+
+## Rule: AUTH_CHECK_AFTER_INIT
+
+After `CometChatUIKit.init()` completes (in its `onSuccess`), the static field `CometChatUIKit.loggedInUser` is already populated if a cached session exists. Use this synchronous check — do NOT call `CometChat.getLoggedInUser()` separately.
+
+```dart
+// ✅ CORRECT — synchronous check after init completes
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) {
+    final hasUser = CometChatUIKit.loggedInUser != null;
+    // Route to home or login based on hasUser
+  },
+);
+
+// ❌ WRONG — separate async getLoggedInUser call after init
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) {
+    CometChat.getLoggedInUser(
+      onSuccess: (user) { ... },  // Unreliable when no session exists
+      onError: (e) { ... },
+    );
+  },
+);
+```
+
+The `init()` method internally calls `getLoggedInUser()` and sets `CometChatUIKit.loggedInUser` before firing `onSuccess`. Calling it again is redundant and the callback-based version can silently fail when no session exists (the SDK logs "Please log in to CometChat before calling this method" and neither callback fires consistently).
+
+This also applies to `login()` and `loginWithAuthToken()` — all three populate `CometChatUIKit.loggedInUser` before calling `onSuccess`.
+
+```dart
+// ❌ ALSO WRONG — async UIKit getLoggedInUser after init (redundant native bridge round-trip)
+CometChatUIKit.init(
+  uiKitSettings: settings,
+  onSuccess: (_) async {
+    final user = await CometChatUIKit.getLoggedInUser(); // Unnecessary!
+    if (user != null) { ... }
+  },
+);
+
+// ❌ ALSO WRONG — raw SDK getLoggedInUser (bypasses UIKit, unreliable)
+User? existingUser = await CometChat.getLoggedInUser();
+```
+
+## Golden Path — Minimal Chat App
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+// 1. Init (once, at app startup)
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'YOUR_APP_ID'
+      ..region = 'us'
+      ..authKey = 'YOUR_AUTH_KEY'
+      ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+await CometChatUIKit.init(uiKitSettings: settings);
+
+// 2. Login
+await CometChatUIKit.loginWithAuthToken('AUTH_TOKEN');
+
+// 3. Show conversations
+CometChatConversations(
+  onItemTap: (conversation) {
+    final user = conversation.conversationWith is User
+        ? conversation.conversationWith as User : null;
+    final group = conversation.conversationWith is Group
+        ? conversation.conversationWith as Group : null;
+    // Navigate to messages screen
+  },
+)
+
+// 4. Messages screen (MUST use resizeToAvoidBottomInset: false)
+Scaffold(
+  resizeToAvoidBottomInset: false, // REQUIRED
+  appBar: CometChatMessageHeader(
+    user: user,
+    group: group,
+    onBack: () => Navigator.pop(context),
+  ),
+  body: Column(
+    children: [
+      Expanded(child: CometChatMessageList(user: user, group: group)),
+      CometChatMessageComposer(user: user, group: group),
+    ],
+  ),
+)
+```
+
+## Complete App Scaffold (main.dart)
+
+Full working app with init → auth guard → login → home → logout. Copy-paste ready.
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+const String appId = 'YOUR_APP_ID';
+const String region = 'us';
+const String authKey = 'YOUR_AUTH_KEY';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  bool _initializing = true;
+  bool _loggedIn = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _initCometChat();
+  }
+
+  void _initCometChat() {
+    final settings = (UIKitSettingsBuilder()
+          ..appId = appId
+          ..region = region
+          ..authKey = authKey
+          ..subscriptionType = CometChatSubscriptionType.allUsers)
+        .build();
+
+    CometChatUIKit.init(
+      uiKitSettings: settings,
+      onSuccess: (_) {
+        // CometChatUIKit.loggedInUser is already set if a cached session exists
+        setState(() {
+          _loggedIn = CometChatUIKit.loggedInUser != null;
+          _initializing = false;
+        });
+      },
+      onError: (e) {
+        debugPrint('Init failed: ${e.message}');
+        setState(() => _initializing = false);
+      },
+    );
+  }
+
+  void _onLoginSuccess() => setState(() => _loggedIn = true);
+
+  void _onLogout() => setState(() => _loggedIn = false);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: _initializing
+          ? const Scaffold(body: Center(child: CircularProgressIndicator()))
+          : _loggedIn
+              ? HomeScreen(onLogout: _onLogout)
+              : LoginScreen(onLoginSuccess: _onLoginSuccess),
+    );
+  }
+}
+
+// --- Login Screen ---
+class LoginScreen extends StatefulWidget {
+  final VoidCallback onLoginSuccess;
+  const LoginScreen({super.key, required this.onLoginSuccess});
+  @override
+  State<LoginScreen> createState() => _LoginScreenState();
+}
+
+class _LoginScreenState extends State<LoginScreen> {
+  final _uidController = TextEditingController();
+  bool _loggingIn = false;
+  String? _error;
+
+  void _login() {
+    final uid = _uidController.text.trim();
+    if (uid.isEmpty) return;
+    setState(() { _loggingIn = true; _error = null; });
+
+    CometChatUIKit.login(uid,
+      onSuccess: (_) {
+        if (mounted) widget.onLoginSuccess();
+      },
+      onError: (e) {
+        if (mounted) setState(() { _loggingIn = false; _error = e.message; });
+      },
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Padding(
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            TextField(
+              controller: _uidController,
+              decoration: const InputDecoration(labelText: 'User ID'),
+            ),
+            const SizedBox(height: 16),
+            if (_error != null)
+              Text(_error!, style: const TextStyle(color: Colors.red)),
+            const SizedBox(height: 16),
+            ElevatedButton(
+              onPressed: _loggingIn ? null : _login,
+              child: _loggingIn
+                  ? const SizedBox(width: 20, height: 20, child: CircularProgressIndicator(strokeWidth: 2))
+                  : const Text('Login'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+// --- Home Screen (Conversations → Messages) ---
+class HomeScreen extends StatelessWidget {
+  final VoidCallback onLogout;
+  const HomeScreen({super.key, required this.onLogout});
+
+  void _logout(BuildContext context) {
+    CometChatUIKit.logout(
+      onSuccess: (_) => onLogout(),
+      onError: (e) => debugPrint('Logout failed: ${e.message}'),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Conversations'),
+        actions: [
+          IconButton(icon: const Icon(Icons.logout), onPressed: () => _logout(context)),
+        ],
+      ),
+      body: CometChatConversations(
+        onItemTap: (conversation) {
+          final user = conversation.conversationWith is User
+              ? conversation.conversationWith as User : null;
+          final group = conversation.conversationWith is Group
+              ? conversation.conversationWith as Group : null;
+          Navigator.push(context, MaterialPageRoute(
+            builder: (_) => MessagesScreen(user: user, group: group),
+          ));
+        },
+      ),
+    );
+  }
+}
+
+// --- Messages Screen ---
+class MessagesScreen extends StatelessWidget {
+  final User? user;
+  final Group? group;
+  const MessagesScreen({super.key, this.user, this.group});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      resizeToAvoidBottomInset: false, // REQUIRED — composer handles keyboard
+      appBar: CometChatMessageHeader(
+        user: user,
+        group: group,
+        onBack: () => Navigator.pop(context),
+      ),
+      body: Column(
+        children: [
+          Expanded(child: CometChatMessageList(user: user, group: group)),
+          CometChatMessageComposer(user: user, group: group),
+        ],
+      ),
+    );
+  }
+}
+```
+
+Key points in this scaffold:
+- `CometChatUIKit.loggedInUser` is checked synchronously after `init()` — no separate `getLoggedInUser()` call
+- State is managed at the `MyApp` level so login/logout transitions are clean
+- `LoginScreen` uses `CometChatUIKit.login(uid)` with auth key (set in UIKitSettings)
+- `MessagesScreen` has `resizeToAvoidBottomInset: false`
+- Logout calls `CometChatUIKit.logout()` and resets state
+
+## 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'` |
+| Double keyboard compensation | Scaffold `resizeToAvoidBottomInset` is true | Set to `false` when using composer |
+| No typing indicators / presence | `subscriptionType` not set | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |
+| Theme jank during keyboard | Theme looked up in `build()` | Cache in `didChangeDependencies()` with `_themeInitialized` flag |
+| Listener leak / duplicate events | Listener not removed in `dispose()` | Always remove with same ID used to register |
+| "ERR_ALREADY_LOGGED_IN" | Calling login when session exists | Check `CometChatUIKit.getLoggedInUser()` first |
+| Messages not updating in real-time | SDK listener not registered | BLoC registers automatically; check component is mounted |
+| Stale user/group data | Passing widget params instead of mutable state | Keep mutable `_user`/`_group` in State, update from listeners |
+| Region error | Uppercase region string | Use lowercase: 'us', 'eu', 'in' |
+| `Android internal error` on login | SDK internal failure — often auth key issue, beta SDK bug, or network | Verify credentials are correct. Try `CometChat.login(uid, authKey)` directly instead of `CometChatUIKit.login(uid)`. Check CometChat dashboard for UID existence. If using beta SDK, try stable release. |
+| Guard screen stuck on spinner | Using `CometChat.getLoggedInUser()` callback API after init | Use `CometChatUIKit.loggedInUser` synchronously after `init()` completes — see AUTH_CHECK_AFTER_INIT rule |
+| Release build crash (ClassNotFoundException) | Missing ProGuard keep rules | Add `-keep class com.cometchat.** { *; }` to `proguard-rules.pro` |
+| Android build fails (minSdk) | minSdk too low | Set `minSdk = 26` in `android/app/build.gradle` |
+| Android build fails (support library) | Missing Jetifier | Add `android.enableJetifier=true` to `gradle.properties` |
+
+## Autonomous Mode
+
+- If `pubspec.yaml` has `cometchat_chat_uikit` → proceed without asking
+- If credentials exist in code → reuse them, don't ask
+- If user says "messages screen" → generate Scaffold + Header + List + Composer with `resizeToAvoidBottomInset: false`
+- Always add `subscriptionType` to UIKitSettingsBuilder
+- Always use `CometChatThemeHelper` for colors, never hardcode
+
+## Android Build Requirements
+
+These are required in your Android project or the build/release will fail:
+
+### gradle.properties
+```properties
+android.useAndroidX=true
+android.enableJetifier=true
+```
+`enableJetifier` resolves old Android Support Library conflicts from transitive dependencies.
+
+### minSdk 26
+In `android/app/build.gradle` (or `.kts`):
+```kotlin
+defaultConfig {
+    minSdk = 26  // Required by cometchat_calls_sdk
+}
+```
+
+### ProGuard / R8 Keep Rules
+Create `android/app/proguard-rules.pro`:
+```
+# CometChat — prevent R8 from stripping SDK classes
+-keep class com.cometchat.** { *; }
+-keep interface com.cometchat.** { *; }
+
+# Suppress warnings for Calls SDK classes referenced cross-module
+-dontwarn com.cometchat.calls.CometChatRTCView$CometChatRTCViewBuilder
+-dontwarn com.cometchat.calls.CometChatRTCView
+-dontwarn com.cometchat.calls.CometChatRTCViewListener
+-dontwarn com.cometchat.calls.model.AnalyticsSettings
+-dontwarn com.cometchat.calls.model.RTCCallback
+-dontwarn com.cometchat.calls.model.RTCReceiver
+```
+
+Reference it in `build.gradle`:
+```kotlin
+buildTypes {
+    release {
+        isMinifyEnabled = true
+        isShrinkResources = true
+        proguardFiles(
+            getDefaultProguardFile("proguard-android-optimize.txt"),
+            "proguard-rules.pro"
+        )
+    }
+}
+```
+
+Without these rules, release builds crash with `ClassNotFoundException` for CometChat classes.