@cometchat/skills 3.0.0 → 4.0.0

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

@@ -0,0 +1,216 @@
+---
+name: cometchat-flutter-v6-users-groups
+description: >
+  Use when implementing user lists, group lists, or group member management with
+  CometChat Flutter UIKit v6. Triggers on mentions of CometChatUsers, CometChatGroups,
+  CometChatGroupMembers, UsersBloc, GroupsBloc, UsersServiceLocator, GroupsServiceLocator,
+  user list, group list, contacts, members, group info, add members, ban members,
+  transfer ownership, change scope, UsersRequestBuilder, GroupsRequestBuilder,
+  GroupMembersRequestBuilder, or customizing user/group list items.
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter_bloc ^8.1.0"
+allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter users groups members contacts"
+---
+
+# CometChat Flutter UIKit — Users & Groups
+
+Components for displaying and managing users, groups, and group members.
+
+## CometChatUsers
+
+Displays a searchable, alphabetically-sorted list of users.
+
+```dart
+CometChatUsers(
+  onItemTap: (context, user) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(user: user),
+    ));
+  },
+  usersStyle: CometChatUsersStyle(
+    backgroundColor: colorPalette.background1,
+  ),
+  usersStatusVisibility: true,
+  showBackButton: true,
+  onBack: () => Navigator.pop(context),
+)
+```
+
+### Custom Request Builder
+
+```dart
+CometChatUsers(
+  usersRequestBuilder: UsersRequestBuilder()
+    ..limit = 30
+    ..friendsOnly = true
+    ..roles = ['default']
+    ..searchKeyword = 'john',
+)
+```
+
+### View Slots
+
+```dart
+CometChatUsers(
+  listItemView: (user) => MyCustomUserItem(user),
+  subtitleView: (context, user) => Text(user.status ?? 'offline'),
+  trailingView: (context, user) => Icon(Icons.chat),
+)
+```
+
+## CometChatGroups
+
+Displays a searchable list of groups with type indicators (public/private/password).
+
+```dart
+CometChatGroups(
+  onItemTap: (context, group) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(group: group),
+    ));
+  },
+  groupsStyle: CometChatGroupsStyle(
+    backgroundColor: colorPalette.background1,
+  ),
+  groupTypeVisibility: true,
+)
+```
+
+### Custom Request Builder
+
+```dart
+CometChatGroups(
+  groupsRequestBuilder: GroupsRequestBuilder()
+    ..limit = 30
+    ..joinedOnly = true
+    ..searchKeyword = 'team'
+    ..withTags = true
+    ..tags = ['project'],
+)
+```
+
+## CometChatGroupMembers
+
+Displays members of a specific group with role indicators and management actions.
+
+```dart
+CometChatGroupMembers(
+  group: group,
+  groupMembersStyle: CometChatGroupMembersStyle(
+    backgroundColor: colorPalette.background1,
+  ),
+)
+```
+
+### Group Member Actions
+
+The component supports scope changes, kick, and ban based on the logged-in user's role:
+
+| Logged-in Role | Can Change Scope | Can Kick | Can Ban |
+|----------------|-----------------|----------|---------|
+| Owner | ✅ All members | ✅ All | ✅ All |
+| Admin | ✅ Participants only | ✅ Participants | ✅ Participants |
+| Participant | ❌ | ❌ | ❌ |
+
+## Architecture (All Three)
+
+All follow the same Clean Architecture + BLoC pattern:
+
+```
+{component}/
+├── bloc/{component}_bloc.dart       # State management + SDK listeners
+├── domain/usecases/                 # Get{Component}sUseCase, etc.
+├── data/repositories/               # SDK wrapper
+├── di/{component}_service_locator.dart  # Singleton DI
+└── widgets/                         # List item, empty/error/loading views
+```
+
+## BLoC State Pattern
+
+All three use the same state pattern:
+
+```dart
+// Status-based states
+{Component}Initial → {Component}Loading → {Component}Loaded / {Component}Empty / {Component}Error
+
+// Loaded state has:
+final List<{Entity}> items;
+final bool hasMore;
+final Set<String> selectedItems;  // For selection mode
+final bool isLoadingMore;
+```
+
+## Selection Mode
+
+All list components support selection:
+
+```dart
+CometChatUsers(
+  selectionMode: SelectionMode.multiple,
+  onSelection: (selectedUsers) {
+    // Handle selected users
+  },
+  activateSelection: ActivateSelection.onLongClick,
+)
+```
+
+## Gotchas
+
+- `CometChatGroupMembers` has been fully migrated to BLoC + Clean Architecture (bloc/, data/, di/, domain/, widgets/). A `GroupMembersBlocAdapter` wraps the BLoC to implement the legacy `CometChatGroupMembersControllerProtocol` for backward compatibility. The old `cometchat_group_members_controller.dart` file still exists but the BLoC is the active implementation.
+- Group type icons (lock for private, shield for password) are controlled by `groupTypeVisibility`. Setting it to `false` hides all type indicators.
+- `friendsOnly: true` on `UsersRequestBuilder` only works if your CometChat plan supports the friends feature.
+- When a user is blocked, they still appear in `CometChatUsers` unless you set `includeBlockedUsers: false` on the conversations BLoC or filter in the request builder.
+
+## Anti-Patterns
+
+```dart
+// ❌ WRONG — not handling group join for password-protected groups
+onItemTap: (context, group) => Navigator.push(context, MaterialPageRoute(
+  builder: (_) => MessagesScreen(group: group), // Fails if not joined
+))
+
+// ✅ CORRECT — check membership, handle password groups
+onItemTap: (context, group) {
+  if (group.hasJoined) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => MessagesScreen(group: group),
+    ));
+  } else if (group.type == GroupTypeConstants.password) {
+    Navigator.push(context, MaterialPageRoute(
+      builder: (_) => JoinProtectedGroupScreen(group: group),
+    ));
+  } else {
+    // Join public group first, then navigate
+  }
+}
+```
+
+```dart
+// ❌ WRONG — hardcoded role check strings
+if (member.scope == 'admin') { ... }
+
+// ✅ CORRECT — use SDK constants
+if (member.scope == GroupMemberScope.admin) { ... }
+```
+
+```dart
+// ❌ WRONG — creating ServiceLocator per widget instance
+final locator = GroupsServiceLocator(); // New instance each time
+
+// ✅ CORRECT — use singleton
+final locator = GroupsServiceLocator.instance;
+locator.setup();
+```
+
+## Checklist
+
+- [ ] `onItemTap` handles group join state (joined vs password vs public)
+- [ ] Group member actions respect role hierarchy
+- [ ] Selection mode configured if multi-select needed
+- [ ] Request builder customized for app's user/group filtering needs
+- [ ] ServiceLocator accessed via `.instance` singleton
+- [ ] Colors from `CometChatThemeHelper`, not hardcoded

package/skills/cometchat-ios/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: cometchat-ios
+description: Entry-point for CometChat iOS UI Kit integration in any Swift/iOS project. Detects the project type, gathers requirements through an interactive conversation, and writes production-quality integration code for UIKit and SwiftUI applications.
+license: "MIT"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat dispatcher entry ios swift uikit swiftui chat messaging"
+---
+
+## Use this skill when
+
+The user wants to add CometChat to any iOS project. Trigger phrases:
+
+- `/cometchat`
+- "add cometchat", "integrate cometchat", "add chat to my app"
+- "add messaging", "add chat ui", "add in-app chat"
+- "integrate chat in ios", "add chat to swift app"
+
+This is the **entry point for iOS integration**. Do NOT invoke
+framework-specific skills directly — this dispatcher detects the
+project type first and routes to the right ones.
+
+**Supported project types:**
+
+| Type | Description |
+|---|---|
+| **UIKit** | Traditional UIKit-based iOS apps using Storyboards or programmatic UI |
+| **SwiftUI** | Modern SwiftUI-based iOS apps |
+| **Hybrid** | Apps using both UIKit and SwiftUI |
+
+The iOS UI Kit loads `CometChatUIKitSwift` via CocoaPods or Swift Package Manager, along with `CometChatSDK`.
+
+## How this skill works
+
+This skill is **interactive and conversational**. You don't just detect
+the project type and dump code. You have a conversation with the developer
+to understand their project, their use case, and exactly where chat
+should go — THEN you write code that fits.
+
+**Pattern skills (loaded from your context):**
+- `cometchat-ios-core` — initialization, login, provider pattern, anti-patterns
+- `cometchat-ios-components` — component catalog, props, composition patterns
+- `cometchat-ios-placement` — WHERE to put chat (navigation, tabs, modals)
+- `cometchat-ios-theming` — customizing colors, fonts, and styles
+- `cometchat-ios-customization` — custom views, templates, formatters
+
+**Key principle: ask, don't assume.** Every piece of information you need
+from the user should be asked explicitly. Don't guess the view controller,
+don't guess where the trigger button goes, don't guess the auth system.
+
+## Steps
+
+### Step 1 — Detect project type + map the project
+
+First, check for iOS project indicators:
+
+**Detection checklist:**
+1. Look for `.xcodeproj` or `.xcworkspace` files
+2. Check for `Podfile` (CocoaPods), `Package.swift` (SPM as a package), or SPM dep refs in `*.xcodeproj/project.pbxproj` (SPM via Xcode GUI)
+3. Read `Info.plist` for app configuration
+4. Check for SwiftUI indicators (`@main App`, `ContentView.swift`)
+5. Check for UIKit indicators (`AppDelegate.swift`, `SceneDelegate.swift`, Storyboards)
+
+**If the project has NO `Podfile`, NO `Package.swift`, AND no SPM refs in the .xcodeproj** (the default state of every freshly Xcode-created `File → New → App` project), STOP. You must establish a dependency-management mechanism before touching integration code. Read `cometchat-ios-core` § 1.0 for the two options (CocoaPods script-able, SPM Xcode-GUI) and complete that step first. Skipping this produces an integration with `import CometChatUIKitSwift` that cannot resolve at build time.
+
+**Then read the project yourself — this is critical.**
+
+- `Podfile`, `Package.swift`, or SPM refs in `*.xcodeproj/project.pbxproj` — existing dependencies
+- The source directory structure — list all directories under the project
+- Find the entry point: `AppDelegate.swift`, `SceneDelegate.swift`, or `@main App`
+- Find existing view controllers or SwiftUI views
+- Find the navigation structure: `UINavigationController`, `UITabBarController`, `NavigationStack`
+
+Store this mental map — you'll use it throughout the conversation.
+
+**Compatibility baselines:**
+- iOS 13+ required for CometChat UI Kit
+- Swift 5.0+ required
+- Xcode 14+ recommended
+
+### Step 2 — Set up credentials (onboarding)
+
+**Ask the user for their CometChat credentials:**
+
+Use `AskUserQuestion`:
+- **question:** "Let's set up CometChat. Do you have your credentials?"
+- **header:** "CometChat Setup"
+- **multiSelect:** false
+- **options:**
+  1. label: "I have my App ID, Region, and Auth Key", description: "I'll paste them now"
+  2. label: "I need to create a CometChat account", description: "Guide me to get credentials"
+  3. label: "I'll set them up later", description: "Just show me the integration code"
+
+**If they have credentials:**
+Ask for:
+1. App ID (from CometChat Dashboard)
+2. Region (`us`, `eu`, or `in`)
+3. Auth Key (for development mode)
+
+**If they need to create an account:**
+Direct them to:
+> "Create a free account at https://app.cometchat.com
+> 1. Sign up and create a new app
+> 2. Go to API & Auth Keys section
+> 3. Copy your App ID, Region, and Auth Key
+> Tell me when you have them."
+
+### Step 3 — Interactive requirements gathering
+
+#### 3a. "What are you building?"
+
+Use `AskUserQuestion`:
+- **question:** "What kind of app are you building?"
+- **header:** "Your app"
+- **multiSelect:** false
+- **options:**
+  1. label: "Messaging app", description: "Chat is the main feature — like WhatsApp, Telegram, or iMessage"
+  2. label: "Marketplace or platform", description: "Buyers and sellers communicate — like Airbnb or eBay"
+  3. label: "SaaS or productivity", description: "Team chat or support chat inside a product"
+  4. label: "Social or community", description: "User profiles with messaging — like a dating app or community"
+  5. label: "Support or helpdesk", description: "Customer-to-agent communication"
+  6. label: "Just exploring", description: "Quick demo — fastest path to see chat working"
+
+**If "Just exploring":** Skip the rest of Step 3 and scaffold the minimal integration — one view controller showing `CometChatConversations` with `cometchat-uid-1` pre-logged-in.
+
+#### 3b. Show what you recommend and why
+
+| Intent | What you'll set up |
+|---|---|
+| **Messaging app** | A dedicated messages tab with conversation list + message view |
+| **Marketplace** | A "Chat with seller" button on product screens + an inbox tab |
+| **SaaS / dashboard** | A chat modal triggered from navigation + a messages section |
+| **Social / community** | A full messenger with tabs: Chats, Calls, Users, Groups |
+| **Support** | A floating chat button that opens a support conversation |
+
+Ask: "Does this sound right, or do you want a different approach?"
+
+#### 3c. Ask where things should go
+
+**Show the user their actual project structure** — list the view controllers/views you found in Step 1.
+
+**For UIKit projects:**
+> "I found these view controllers in your project:
+>   - MainViewController
+>   - ProfileViewController
+>   - SettingsViewController
+>
+> Where should the messages screen be accessible from?"
+
+**For SwiftUI projects:**
+> "I found these views in your project:
+>   - ContentView
+>   - HomeView
+>   - ProfileView
+>
+> Where should the messages view be accessible from?"
+
+#### 3d. Detect and ask about authentication
+
+Look for auth libraries in the project:
+- `FirebaseAuth` → Firebase Authentication
+- `AuthenticationServices` → Sign in with Apple
+- `GoogleSignIn` → Google Sign-In
+- Custom auth patterns
+
+Report what you found and ask:
+
+If auth detected:
+> "I see you're using [Firebase Auth / etc.]. Here's how CometChat will work:
+>
+> - **Development (now):** I'll use CometChat's Auth Key for quick testing
+> - **Production (later):** Your server will mint per-user auth tokens
+>
+> Start with dev mode for now?"
+
+If no auth detected:
+> "I don't see an authentication system yet. For now, I'll set up CometChat
+> with a hardcoded test user (cometchat-uid-1).
+>
+> When you add auth later, you can connect them."
+
+#### 3e. Confirm the plan
+
+**Show EXACTLY what you'll do before doing it:**
+
+> "Here's what I'll create:
+>
+> **New files:**
+> - `CometChatManager.swift` — initialization and login handling
+> - `ChatViewController.swift` — main chat interface
+>
+> **Files I'll modify:**
+> - `AppDelegate.swift` — add CometChat initialization
+> - `MainViewController.swift` — add navigation to chat
+>
+> **Dependencies:** CometChatUIKitSwift, CometChatSDK
+>
+> **Auth mode:** Development (Auth Key)
+>
+> Proceed? [y/n]"
+
+Wait for explicit confirmation.
+
+### Step 4 — Reference pattern skills
+
+**All skills are already loaded in your context.** Read and follow them directly:
+
+1. `cometchat-ios-core` — initialization, login, provider pattern
+2. `cometchat-ios-components` — component catalog, composition patterns
+3. `cometchat-ios-placement` — placement pattern for the chosen approach
+4. `cometchat-ios-theming` — if customization is needed
+
+### Step 5 — Write the integration
+
+Execute the confirmed plan:
+
+1. **Add dependencies** — CocoaPods or SPM
+2. **CometChatManager** — singleton for init/login
+3. **Chat UI** — appropriate components for the use case
+4. **Wire into existing project** — READ each file before modifying
+5. **Environment setup** — credentials configuration
+
+### Step 6 — Verify + show result
+
+After writing code:
+
+1. Verify the project builds
+2. Check for any missing imports
+3. Surface any common issues
+
+**Result message:**
+> "CometChat is integrated! Here's what was set up:
+>
+> - CometChatManager.swift ✓
+> - ChatViewController.swift ✓
+> - Dependencies added ✓
+>
+> Next steps:
+> 1. Run `pod install` (if using CocoaPods)
+> 2. Build and run the app
+> 3. Navigate to the chat screen
+>
+> **About the empty conversation list:**
+> Every CometChat app has 5 pre-created test users: `cometchat-uid-1` through `uid-5`.
+> To see chat working:
+> 1. Open https://app.cometchat.com → your app → Users
+> 2. Send a message from `cometchat-uid-2` to `cometchat-uid-1`
+> 3. Refresh the app to see the conversation"
+
+### Step 7 — Iteration menu
+
+Use `AskUserQuestion`:
+- **question:** "What would you like to do next?"
+- **header:** "Next step"
+- **options:**
+  1. label: "Customize look and feel", description: "Change colors, fonts, and styles"
+  2. label: "Add a feature", description: "Calls, reactions, polls, AI features"
+  3. label: "Customize a component", description: "Custom message bubbles, headers, etc."
+  4. label: "Set up push notifications", description: "APNs setup for message notifications"
+  5. label: "Set up production auth", description: "Replace dev Auth Key with server tokens"
+  6. label: "Troubleshoot an issue", description: "Debug common problems"
+  7. label: "I'm done", description: "Exit"
+
+## Hard rules
+
+### Always
+
+- **Ask, don't assume.** Every integration decision should be confirmed.
+- **Always detect project type first.** Do not assume UIKit or SwiftUI.
+- NEVER replace existing project files unless the user explicitly confirms.
+- ALWAYS read existing files before modifying them.
+- ALWAYS show the plan and get confirmation before writing.
+- For component names and properties, use the `cometchat-ios-components` skill — never invent from training data.
+
+### iOS-specific
+
+- **Initialize CometChat in AppDelegate or App init** — before any UI renders
+- **Use the singleton pattern** for CometChatManager
+- **Handle async initialization properly** — don't show chat UI until init completes
+- **Respect iOS lifecycle** — handle background/foreground transitions
+- **Support both light and dark mode** — use CometChatTheme
+
+## Error handling
+
+Common iOS integration errors:
+
+| Error | Cause | Solution |
+|---|---|---|
+| "CometChat is not initialized" | UI shown before init completes | Use completion handler pattern |
+| "Invalid App ID" | Wrong credentials | Verify App ID in dashboard |
+| "Module not found" | Dependencies not installed | Run `pod install` or add SPM package |
+| Build errors | Missing imports | Add `import CometChatUIKitSwift` |
+
+## Skill routing reference
+
+| Skill | When to load |
+|---|---|
+| `cometchat-ios-core` | Always — before any integration code |
+| `cometchat-ios-components` | Always — before writing component code |
+| `cometchat-ios-placement` | When integrating — for placement patterns |
+| `cometchat-ios-theming` | When customizing themes |
+| `cometchat-ios-customization` | When writing custom views or templates |
+| `cometchat-ios-features` | When adding calls, reactions, polls, AI features |
+| `cometchat-ios-push` | When setting up push notifications |
+| `cometchat-ios-production` | When setting up production auth |
+| `cometchat-ios-troubleshooting` | When diagnosing problems |
+
+## Complete Skill Set
+
+This iOS UI Kit skill set includes 9 comprehensive skills:
+
+1. **cometchat-ios** (this file) — Entry-point dispatcher
+2. **cometchat-ios-core** — Initialization, login, manager pattern
+3. **cometchat-ios-components** — Complete component catalog
+4. **cometchat-ios-placement** — Navigation patterns, tabs, modals
+5. **cometchat-ios-theming** — Colors, fonts, dark mode
+6. **cometchat-ios-customization** — Custom views, templates, formatters
+7. **cometchat-ios-features** — Calls, reactions, polls, AI, extensions
+8. **cometchat-ios-push** — Push notifications setup
+9. **cometchat-ios-production** — Server-side auth, security
+10. **cometchat-ios-troubleshooting** — Common issues and debugging