@cometchat/skills 3.0.0 → 4.0.0

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

@@ -0,0 +1,207 @@
+---
+name: cometchat-flutter-v5-production
+description: "Use when preparing a CometChat Flutter UIKit v5 app for production. Covers auth tokens, ProGuard, environment config, security hardening."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 production security auth tokens proguard environment"
+---
+
+# CometChat Flutter UIKit v5 — Production
+
+Hardening a CometChat Flutter app for production deployment.
+
+## Auth Tokens vs Auth Key
+
+**Development:** `CometChatUIKit.login(uid)` uses `authKey` from `UIKitSettingsBuilder`. This is convenient but insecure — the authKey is embedded in the app binary.
+
+**Production:** Use server-minted auth tokens via `CometChatUIKit.loginWithAuthToken(authToken)`:
+
+```dart
+// 1. Your backend generates an auth token via CometChat REST API
+// POST https://{appId}.api-{region}.cometchat.io/v3/users/{uid}/auth_tokens
+// Header: apiKey: YOUR_API_KEY
+
+// 2. Your Flutter app receives the token and logs in
+CometChatUIKit.loginWithAuthToken(authToken,
+  onSuccess: (user) { ... },
+  onError: (e) { ... },
+);
+```
+
+This keeps the API key on your server, never in the client.
+
+## Environment Configuration
+
+Store credentials outside source code:
+
+```dart
+class AppCredentials {
+  static String _appId = '';
+  static String _authKey = '';
+  static String _region = '';
+
+  // Load from SharedPreferences, environment, or remote config
+  static String get appId => _appId.isEmpty
+      ? SharedPreferencesClass.getString('appId')
+      : _appId;
+
+  static Future<void> setAppId(String value) async {
+    await SharedPreferencesClass.setString('appId', value);
+    _appId = value;
+  }
+}
+```
+
+The master app supports QR code scanning to load credentials dynamically (`CometChatQRScreen`).
+
+## Android Build Requirements
+
+### gradle.properties
+
+```properties
+android.useAndroidX=true
+android.enableJetifier=true
+```
+
+### minSdk 26
+
+```groovy
+// android/app/build.gradle
+defaultConfig {
+    minSdk 26  // Required by cometchat_calls_sdk
+}
+```
+
+### ProGuard / R8 Keep Rules
+
+Create `android/app/proguard-rules.pro`:
+
+```
+-keep class com.cometchat.** { *; }
+-keep interface com.cometchat.** { *; }
+-dontwarn com.cometchat.calls.**
+```
+
+Reference in `build.gradle`:
+
+```groovy
+buildTypes {
+    release {
+        minifyEnabled true
+        shrinkResources true
+        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+    }
+}
+```
+
+### Signing
+
+```groovy
+signingConfigs {
+    release {
+        storeFile file('your_keystore.jks')
+        storePassword 'STORE_PASSWORD'
+        keyAlias 'KEY_ALIAS'
+        keyPassword 'KEY_PASSWORD'
+    }
+}
+```
+
+## iOS Build Requirements
+
+### Info.plist Permissions
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access for video calls and photo sharing</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>Microphone access for voice and video calls</string>
+<key>NSPhotoLibraryUsageDescription</key>
+<string>Photo library access for sharing images</string>
+```
+
+### Background Modes (for VoIP)
+
+Enable in Xcode: Background Modes → Voice over IP, Remote notifications, Background fetch.
+
+### Podfile
+
+Ensure minimum iOS deployment target matches CometChat requirements.
+
+## Firebase Setup
+
+```dart
+// In main(), before runApp:
+await Firebase.initializeApp(
+  options: DefaultFirebaseOptions.currentPlatform,
+);
+```
+
+### Crashlytics
+
+```dart
+FlutterError.onError = (errorDetails) {
+  FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
+};
+PlatformDispatcher.instance.onError = (error, stack) {
+  FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
+  return true;
+};
+```
+
+## Push Notification Provider IDs
+
+Configure provider IDs for FCM and APNs in the CometChat dashboard:
+
+```dart
+static String get fcmProviderId => 'your-fcm-provider-id';
+static String get apnProviderId => 'your-apn-provider-id';
+```
+
+These must match what's configured in the CometChat dashboard under Notifications → Push Notifications.
+
+## Demo Meta Info
+
+For internal tracking (optional):
+
+```dart
+CometChat.setDemoMetaInfo(jsonObject: {
+  "name": "flutter-sample-app",
+  "type": "sample",
+  "version": "5.2.11",
+  "platform": "flutter",
+});
+```
+
+## Logout Flow
+
+```dart
+// 1. Unregister push tokens
+PNRegistry.unregisterPNService();
+
+// 2. Sign out from Firebase/Google (if applicable)
+await FirebaseAuth.instance.signOut();
+await GoogleSignIn().signOut();
+
+// 3. Logout from CometChat
+await CometChatUIKit.logout(
+  onSuccess: (_) { /* navigate to login */ },
+  onError: (e) { /* show error */ },
+);
+```
+
+## Checklist — Production
+
+- [ ] Auth tokens minted server-side, not authKey in client
+- [ ] Credentials not hardcoded in source (use SharedPreferences or remote config)
+- [ ] ProGuard rules added for release builds
+- [ ] minSdk 26 set
+- [ ] iOS permissions in Info.plist
+- [ ] Firebase Crashlytics configured
+- [ ] Push notification provider IDs match CometChat dashboard
+- [ ] Logout unregisters push tokens before CometChat logout
+- [ ] Signing config set for release builds

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

@@ -0,0 +1,284 @@
+---
+name: cometchat-flutter-v5-push
+description: "Use when implementing push notifications with CometChat Flutter UIKit v5. Covers FCM (Android), APNs (iOS), VoIP calls, token lifecycle, local notifications, and tap-to-navigate."
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; firebase_messaging; flutter_local_notifications; flutter_callkit_incoming"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 push notifications fcm apns voip callkit firebase"
+---
+
+# CometChat Flutter UIKit v5 — Push Notifications
+
+Push notification setup for Android (FCM) and iOS (APNs + VoIP).
+
+## Dependencies
+
+```yaml
+dependencies:
+  firebase_core: ^3.9.0
+  firebase_messaging: ^15.1.6
+  flutter_local_notifications: ^18.0.0
+  flutter_callkit_incoming: # for VoIP call notifications
+  app_badge_plus: ^1.2.6  # badge count
+```
+
+## Architecture Overview
+
+```
+notifications/
+├── models/
+│   ├── payload.dart              # PayloadData model for parsing FCM data
+│   ├── call_action.dart          # CallAction enum (initiated, cancelled, unanswered)
+│   ├── call_type.dart            # CallType enum (audio, video)
+│   └── notification_message_type.dart  # Message type constants
+├── services/
+│   ├── android_notification_service/
+│   │   ├── firebase_services.dart       # FCM init, listeners, token management
+│   │   ├── local_notification_handler.dart  # Local notification display + tap handling
+│   │   ├── voip_notification_handler.dart   # VoIP call display, accept, decline
+│   │   └── notification_launch_handler.dart # Terminated state launch handling
+│   ├── iOS_notification_service/
+│   │   └── apns_services.dart           # APNs connector, VoIP token, CallKit
+│   └── cometchat_service/
+│       └── cometchat_services.dart      # PNRegistry (token registration/unregistration)
+```
+
+## Token Registration — `CometChatNotifications.registerPushToken`
+
+The kit's only public push surface is `CometChatNotifications.registerPushToken(platform, {providerId, fcmToken, deviceToken, voipToken, onSuccess, onError})` (and `unregisterPushToken({onSuccess, onError})`). The sample app wraps this in an extension named `PNRegistry on CometChatService` (see `sample_app_push_notifications/lib/notifications/services/cometchat_service/cometchat_services.dart`) that picks the right provider ID + platform constant for FCM-Android / FCM-iOS / APNs / APNs-VoIP. **Copy that helper into your project, or call `CometChatNotifications.registerPushToken` directly** — `PNRegistry` is a sample-app extension, not importable from any cometchat package.
+
+```dart
+// Direct kit API:
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+await CometChatNotifications.registerPushToken(
+  PushPlatforms.FCM_FLUTTER_ANDROID,    // platform — first positional arg
+  providerId: fcmProviderId,            // dashboard FCM provider ID
+  fcmToken: token,                      // use fcmToken / deviceToken / voipToken depending on platform
+  onSuccess: (response) => debugPrint('registered: $response'),
+  onError: (e) => debugPrint('register failed: $e'),
+);
+
+// On logout:
+await CometChatNotifications.unregisterPushToken(
+  onSuccess: (_) {},
+  onError: (e) => debugPrint('unregister failed: $e'),
+);
+```
+
+```dart
+// Or use the sample-app PNRegistry helper after copying it into your project:
+PNRegistry.registerPNService(token, true, false);   // (token, isFcm, isVoip)
+PNRegistry.unregisterPNService();
+```
+
+Platform mapping:
+- FCM Android → `PushPlatforms.FCM_FLUTTER_ANDROID`
+- FCM iOS → `PushPlatforms.FCM_FLUTTER_IOS`
+- APNs Device → `PushPlatforms.APNS_FLUTTER_DEVICE`
+- APNs VoIP → `PushPlatforms.APNS_FLUTTER_VOIP`
+
+Provider IDs come from `AppCredentials.fcmProviderId` / `AppCredentials.apnProviderId` (your own constants — these are dashboard-configured values, not kit exports).
+
+The remaining examples below assume you've copied `PNRegistry` from the sample app. If you call `CometChatNotifications.registerPushToken` directly, swap the call sites accordingly.
+
+## Android — FCM Setup
+
+### 1. Background handler (must be top-level function)
+
+```dart
+@pragma('vm:entry-point')
+Future<void> firebaseMessagingBackgroundHandler(RemoteMessage rMessage) async {
+  LocalNotificationService.showNotification(rMessage.data, rMessage, "", false);
+  await VoipNotificationHandler.displayIncomingCall(rMessage);
+}
+```
+
+### 2. Initialize in dashboard/home screen
+
+```dart
+class FirebaseService {
+  Future<void> init(BuildContext context) async {
+    _firebaseMessaging = FirebaseMessaging.instance;
+    await requestPermissions();
+    await initListeners(context);
+
+    String? token = await _firebaseMessaging.getToken();
+    if (token != null) {
+      PNRegistry.registerPNService(token, true, false);
+    }
+  }
+}
+```
+
+### 3. Listener setup
+
+```dart
+// Background messages
+FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
+
+// Token refresh
+_firebaseMessaging.onTokenRefresh.listen((token) {
+  PNRegistry.registerPNService(token, true, false);
+});
+
+// Foreground messages
+FirebaseMessaging.onMessage.listen((message) {
+  LocalNotificationService.showNotification(message.data, message, conversationId, isAgentic);
+});
+
+// Tap from background
+FirebaseMessaging.onMessageOpenedApp.listen((message) {
+  openNotification(context, message, conversationId);
+});
+
+// Tap from terminated state
+FirebaseMessaging.instance.getInitialMessage().then((message) {
+  if (message != null) openNotification(context, message, conversationId);
+});
+```
+
+## iOS — APNs Setup
+
+```dart
+final _connector = ApnsPushConnector();
+_connector.shouldPresent = (x) => Future.value(false);
+
+_connector.configure(
+  onLaunch: (message) async { openNotification(message, context, ""); },
+  onResume: (message) async { openNotification(message, context, conversationId); },
+  onMessage: (message) async { _showNotification(message.data, message, conversationId, isAgentic); },
+);
+
+_connector.requestNotificationPermissions();
+
+// APNs device token
+_connector.token.addListener(() {
+  PNRegistry.registerPNService(_connector.token.value!, false, false);
+});
+
+// VoIP token
+FlutterCallkitIncoming.getDevicePushTokenVoIP().then((voipToken) {
+  PNRegistry.registerPNService(voipToken, false, true);
+});
+```
+
+## VoIP Call Notifications
+
+### Display incoming call (both platforms)
+
+```dart
+static Future<void> displayIncomingCall(RemoteMessage rMessage) async {
+  PayloadData callPayload = PayloadData.fromJson(rMessage.data);
+  if (callPayload.type == 'call' && callPayload.callAction == CallAction.initiated) {
+    CallKitParams params = CallKitParams(
+      id: callPayload.sessionId,
+      nameCaller: callPayload.senderName,
+      type: (callPayload.callType == CallType.audio) ? 0 : 1,
+      duration: 45000,
+    );
+    await FlutterCallkitIncoming.showCallkitIncoming(params);
+  }
+}
+```
+
+### Accept/Decline via CallKit events
+
+```dart
+FlutterCallkitIncoming.onEvent.listen((CallEvent? callEvent) {
+  switch (callEvent?.event) {
+    case Event.actionCallAccept:
+      VoipNotificationHandler.acceptVoipCall(callEvent, context);
+      break;
+    case Event.actionCallDecline:
+      VoipNotificationHandler.declineVoipCall(callEvent);
+      break;
+    case Event.actionCallTimeout:
+    case Event.actionCallEnded:
+      VoipNotificationHandler.endCall(sessionId: callEvent?.body['id']);
+      break;
+  }
+});
+```
+
+## Local Notification Display
+
+Uses `flutter_local_notifications` with inbox-style grouping per conversation:
+
+```dart
+// Skip if user is viewing the same conversation
+if (conversationId == notifConversationId) return;
+
+// Skip call-type notifications (handled by CallKit)
+if (data["type"] == "call") return;
+
+// Show with stable ID per conversation (replaces previous)
+final notificationId = conversationId.hashCode;
+await flutterLocalNotificationsPlugin.show(notificationId, title, body, details, payload: jsonPayload);
+```
+
+## Tap-to-Navigate
+
+```dart
+static void handleNotificationTap(NotificationResponse? response) async {
+  if (response?.payload != null) {
+    final body = jsonDecode(response!.payload!);
+    NotificationDataModel model = NotificationDataModel.fromJson(body);
+
+    User? user; Group? group;
+    if (model.receiverType == "user") {
+      user = await CometChat.getUser(model.sender);
+    } else {
+      group = await CometChat.getGroup(model.receiver);
+    }
+
+    if (model.type == "chat" && (user != null || group != null)) {
+      Navigator.of(CallNavigationContext.navigatorKey.currentContext!).push(
+        MaterialPageRoute(builder: (_) => MessagesSample(user: user, group: group)),
+      );
+    }
+  }
+}
+```
+
+## Terminated State Handling
+
+```dart
+// In main()
+final launchDetails = await flutterLocalNotificationsPlugin.getNotificationAppLaunchDetails();
+if (launchDetails?.didNotificationLaunchApp == true) {
+  NotificationLaunchHandler.pendingNotificationResponse = launchDetails!.notificationResponse;
+}
+
+// In dashboard initState()
+Future.delayed(Duration(milliseconds: 300), () {
+  final response = NotificationLaunchHandler.pendingNotificationResponse;
+  if (response != null) {
+    NotificationLaunchHandler.pendingNotificationResponse = null;
+    LocalNotificationService.handleNotificationTap(response, isTerminatedState: true);
+  }
+});
+```
+
+## Logout — Unregister Token
+
+```dart
+PNRegistry.unregisterPNService();
+// Then: CometChatUIKit.logout(...)
+```
+
+## Checklist — Push Notifications
+
+- [ ] Firebase initialized before CometChat init
+- [ ] FCM token registered via `PNRegistry.registerPNService(token, true, false)`
+- [ ] APNs device + VoIP tokens registered on iOS
+- [ ] Background handler is top-level `@pragma('vm:entry-point')` function
+- [ ] Token refresh listener re-registers token
+- [ ] Local notifications skip current active conversation
+- [ ] Call notifications handled via `FlutterCallkitIncoming`, not local notifications
+- [ ] Tap-to-navigate uses `CallNavigationContext.navigatorKey.currentContext`
+- [ ] Tokens unregistered on logout via `PNRegistry.unregisterPNService()`
+- [ ] Terminated state launch handled via `NotificationLaunchHandler`

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

@@ -0,0 +1,160 @@
+---
+name: cometchat-flutter-v5-theming
+description: "Use when customizing the visual appearance of CometChat Flutter UIKit v5 components. Triggers on CometChatThemeHelper, CometChatColorPalette, CometChatSpacing, CometChatTypography, Style classes, merge()."
+license: "MIT"
+compatibility: "cometchat_uikit_shared ^5.2.3; flutter >=2.5.0"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter v5 theme colors typography spacing dark-mode styling"
+---
+
+# CometChat Flutter UIKit v5 — Theming & Styling
+
+How to customize the visual appearance of all CometChat v5 components.
+
+## Theme System Architecture
+
+Three layers, resolved via Flutter's `ThemeExtension` system:
+
+1. `CometChatColorPalette` — colors (primary, neutral, alert, background, text, icon, button, border)
+2. `CometChatSpacing` — spacing, padding, margin, and radius tokens
+3. `CometChatTypography` — text styles (heading1-4, body, caption1-2, button, link, title)
+
+Access via static helpers:
+```dart
+final colors = CometChatThemeHelper.getColorPalette(context);
+final spacing = CometChatThemeHelper.getSpacing(context);
+final typography = CometChatThemeHelper.getTypography(context);
+```
+
+**Important:** `getColorPalette()` creates a new object every call, resolving each token via `Theme.of(context)`. Cache in `didChangeDependencies()`, never call in `build()`.
+
+## Applying a Custom Theme
+
+Register `CometChatColorPalette` as a `ThemeExtension` on your `ThemeData`:
+
+```dart
+// ✅ CORRECT
+MaterialApp(
+  theme: ThemeData(
+    extensions: [
+      CometChatColorPalette(
+        primary: const Color(0xFF6852D6),
+        textPrimary: const Color(0xFF141414),
+        textSecondary: const Color(0xFF727272),
+      ),
+    ],
+  ),
+  darkTheme: ThemeData(
+    extensions: [
+      CometChatColorPalette(
+        primary: const Color(0xFF604CC3),
+        textPrimary: const Color(0xFFFFFFFF),
+        textSecondary: const Color(0xFFA0A0A0),
+      ),
+    ],
+  ),
+)
+```
+
+## Dark Mode
+
+```dart
+CometChatThemeMode.mode = ThemeMode.dark;   // Force dark
+CometChatThemeMode.mode = ThemeMode.system;  // Follow system
+```
+
+## Commonly Used Color Tokens
+
+| Token | Description | Light Default | Dark Default |
+|-------|-------------|---------------|--------------|
+| `primary` | Brand color | `#6852D6` | `#604CC3` |
+| `background1`–`4` | Surface backgrounds | neutral50→neutral300 | neutral50→neutral300 |
+| `textPrimary` | Main text | neutral900 | neutral900 |
+| `textSecondary` | Secondary text | neutral600 | neutral600 |
+| `borderLight` | Subtle borders | neutral200 | neutral200 |
+| `iconPrimary` | Main icons | neutral900 | neutral900 |
+| `iconSecondary` | Secondary icons | neutral500 | neutral500 |
+| `iconHighlight` | Highlighted icons | primary | primary |
+| `error` | Error states | `#F44649` | `#C73C3E` |
+| `white` / `black` | Fixed (NOT brightness-aware) | `Colors.white` / `Colors.black` | Same |
+| `transparent` | Transparent | `Colors.transparent` | Same |
+| `neutral600` | Used for date styles | — | — |
+
+Extended primary shades (`extendedPrimary50`–`900`) are auto-generated from `primary`. Override individually if needed.
+
+## Commonly Used Spacing Tokens
+
+| Token | Default |
+|-------|---------|
+| `padding` / `spacing` / `radius` | 2 |
+| `padding1` / `spacing1` / `radius1` | 4 |
+| `padding2` / `spacing2` / `radius2` | 8 |
+| `padding3` / `spacing3` / `radius3` | 12 |
+| `padding4` / `spacing4` / `radius4` | 16 |
+| `padding5` / `spacing5` / `radius5` | 20 |
+| `padding6` / `spacing6` | 24 |
+| `radiusMax` / `spacingMax` | 1000 |
+
+## Typography Tokens
+
+`CometChatTypography` provides: `heading1`–`heading4`, `body`, `caption1`, `caption2`, `button`, `link`, `title`.
+
+Each has `.bold`, `.medium`, `.regular` variants:
+```dart
+typography.body?.regular?.fontSize
+typography.heading2?.bold?.fontWeight
+typography.caption1?.regular?.fontFamily
+```
+
+## Theme Caching Pattern (from package source)
+
+All UIKit components cache theme unconditionally in `didChangeDependencies()`:
+
+```dart
+// ✅ CORRECT — matches actual package pattern
+@override
+void didChangeDependencies() {
+  super.didChangeDependencies();
+  colorPalette = CometChatThemeHelper.getColorPalette(context);
+  spacing = CometChatThemeHelper.getSpacing(context);
+  typography = CometChatThemeHelper.getTypography(context);
+}
+```
+
+Do NOT use a `_themeInitialized` flag — it prevents theme updates on system theme changes.
+
+## Component Style Classes — merge() Pattern
+
+Every component has a `CometChat{Component}Style` extending `ThemeExtension`. Resolved internally:
+
+```dart
+// Inside component's didChangeDependencies():
+style = CometChatThemeHelper.getTheme<CometChatConversationsStyle>(
+    context: context,
+    defaultTheme: CometChatConversationsStyle.of,
+).merge(widget.conversationsStyle);
+```
+
+Pass overrides via constructor:
+```dart
+CometChatConversations(
+  conversationsStyle: CometChatConversationsStyle(
+    backgroundColor: Colors.black,
+  ),
+)
+```
+
+## Gotchas
+
+- `colorPalette.white` / `black` / `transparent` are NOT brightness-aware — use `neutral50` for brightness-aware white
+- Extended primary shades auto-generated from `primary` by blending with white (light) or black (dark)
+
+## Checklist — Theming
+
+- [ ] Colors from `CometChatThemeHelper.getColorPalette(context)`, never hardcoded
+- [ ] Theme cached in `didChangeDependencies()`, not `build()`
+- [ ] Custom theme registered as `ThemeExtension` on both `theme` and `darkTheme`
+- [ ] Component styles passed via constructor props