@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-android-v5-customization/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: cometchat-android-v5-customization
+description: "Customize CometChat components beyond theming — custom message templates, DataSource decorators, event listeners, and custom view slots."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, grepSearch"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android customization custom-view message-template datasource events"
+---
+
+> **Companion skills:** `cometchat-android-v5-components` provides the component
+> catalog; `cometchat-android-v5-theming` covers visual styling;
+> `cometchat-android-v5-extensions` covers the extension architecture.
+
+## Purpose
+
+This skill teaches how to customize CometChat components beyond what theming provides. It covers custom message templates, the DataSource/DataSourceDecorator pattern, ChatConfigurator, event listeners, and custom view slots.
+
+---
+
+## Use this skill when
+
+- "Customize the message list"
+- "Add a custom message bubble"
+- "Listen to message events"
+- "Add a custom action to message options"
+- "Filter conversations"
+
+## Do not use this skill when
+
+- Changing colors/fonts → use `cometchat-android-v5-theming`
+- Enabling a packaged feature → use `cometchat-android-v5-features`
+- Setting up init/login → use `cometchat-android-v5-core`
+
+---
+
+## 1. CometChatMessageTemplate
+
+Templates define how message bubbles are rendered. Each template maps a message `type` + `category` to custom views.
+
+**Java:**
+```java
+CometChatMessageTemplate template = new CometChatMessageTemplate()
+    .setType(CometChatConstants.MESSAGE_TYPE_TEXT)
+    .setCategory(CometChatConstants.CATEGORY_MESSAGE)
+    .setContentView(new MessagesViewHolderListener() {
+        @Override
+        public View createView(Context context, CometChatMessageBubble messageBubble,
+                               UIKitConstants.MessageBubbleAlignment alignment) {
+            // Return your custom view
+            return LayoutInflater.from(context).inflate(R.layout.custom_text_bubble, null);
+        }
+
+        @Override
+        public void bindView(Context context, View createdView, BaseMessage message,
+                             UIKitConstants.MessageBubbleAlignment alignment,
+                             RecyclerView.ViewHolder holder, List<BaseMessage> messageList,
+                             int position) {
+            // Bind data to your custom view
+            TextView textView = createdView.findViewById(R.id.customText);
+            textView.setText(((TextMessage) message).getText());
+        }
+    })
+    .setOptions((context, baseMessage, group) -> {
+        // Return custom message options (long-press menu)
+        List<CometChatMessageOption> options = new ArrayList<>();
+        options.add(new CometChatMessageOption("custom_action", "Custom Action",
+            R.drawable.ic_custom, () -> { /* handle click */ }));
+        return options;
+    });
+
+// Apply to message list
+messageList.setTemplates(Collections.singletonList(template));
+```
+
+**Kotlin:**
+```kotlin
+val template = CometChatMessageTemplate()
+    .setType(CometChatConstants.MESSAGE_TYPE_TEXT)
+    .setCategory(CometChatConstants.CATEGORY_MESSAGE)
+    .setContentView(object : MessagesViewHolderListener() {
+        override fun createView(context: Context, messageBubble: CometChatMessageBubble,
+                                alignment: UIKitConstants.MessageBubbleAlignment): View {
+            return LayoutInflater.from(context).inflate(R.layout.custom_text_bubble, null)
+        }
+
+        override fun bindView(context: Context, createdView: View, message: BaseMessage,
+                              alignment: UIKitConstants.MessageBubbleAlignment,
+                              holder: RecyclerView.ViewHolder, messageList: List<BaseMessage>,
+                              position: Int) {
+            val textView = createdView.findViewById<TextView>(R.id.customText)
+            textView.text = (message as TextMessage).text
+        }
+    })
+    .setOptions { context, baseMessage, group ->
+        listOf(CometChatMessageOption("custom_action", "Custom Action",
+            R.drawable.ic_custom) { /* handle click */ })
+    }
+
+messageList.setTemplates(listOf(template))
+```
+
+### Template view slots
+
+| Slot | Method | Description |
+|---|---|---|
+| `bubbleView` | `setBubbleView(MessagesViewHolderListener)` | Entire message bubble |
+| `headerView` | `setHeaderView(MessagesViewHolderListener)` | Above the bubble |
+| `contentView` | `setContentView(MessagesViewHolderListener)` | Inside the bubble |
+| `bottomView` | `setBottomView(MessagesViewHolderListener)` | Below the content, inside bubble |
+| `footerView` | `setFooterView(MessagesViewHolderListener)` | Below the bubble |
+| `statusInfoView` | `setStatusInfoView(MessagesViewHolderListener)` | Status info area |
+| `replyView` | `setReplyView(MessagesViewHolderListener)` | Reply preview above bubble |
+
+---
+
+## 2. CometChatMessageOption
+
+Custom actions in the message long-press menu.
+
+**Java:**
+```java
+CometChatMessageOption option = new CometChatMessageOption(
+    "bookmark",                    // unique ID
+    "Bookmark",                    // title
+    R.drawable.ic_bookmark,        // icon
+    () -> {                        // onClick
+        // Handle bookmark action
+    }
+);
+```
+
+---
+
+## 3. DataSource and DataSourceDecorator
+
+The `DataSource` interface defines how messages are rendered and what options are available. `DataSourceDecorator` wraps an existing DataSource to add or modify behavior without replacing it.
+
+**Java:**
+```java
+public class CustomDataSource extends DataSourceDecorator {
+    public CustomDataSource(DataSource dataSource) {
+        super(dataSource);
+    }
+
+    @Override
+    public List<CometChatMessageOption> getTextMessageOptions(Context context,
+            BaseMessage baseMessage, Group group, AdditionParameter additionParameter) {
+        List<CometChatMessageOption> options = super.getTextMessageOptions(context,
+            baseMessage, group, additionParameter);
+        // Add custom option
+        options.add(new CometChatMessageOption("translate", "Translate",
+            R.drawable.ic_translate, () -> { /* translate */ }));
+        return options;
+    }
+}
+```
+
+**Kotlin:**
+```kotlin
+class CustomDataSource(dataSource: DataSource) : DataSourceDecorator(dataSource) {
+    override fun getTextMessageOptions(context: Context, baseMessage: BaseMessage,
+            group: Group?, additionParameter: AdditionParameter): List<CometChatMessageOption> {
+        val options = super.getTextMessageOptions(context, baseMessage, group, additionParameter).toMutableList()
+        options.add(CometChatMessageOption("translate", "Translate",
+            R.drawable.ic_translate) { /* translate */ })
+        return options
+    }
+}
+```
+
+### Register via ChatConfigurator
+
+**Java:**
+```java
+ChatConfigurator.enable(dataSource -> new CustomDataSource(dataSource));
+```
+
+**Kotlin:**
+```kotlin
+ChatConfigurator.enable { dataSource -> CustomDataSource(dataSource) }
+```
+
+---
+
+## 4. Event system
+
+CometChat provides event classes for reacting to chat events. Register listeners with a unique tag.
+
+### CometChatMessageEvents
+
+**Java:**
+```java
+CometChatMessageEvents.addListener("unique-tag", new CometChatMessageEvents() {
+    @Override
+    public void ccMessageSent(BaseMessage baseMessage, int status) {
+        // Message sent
+    }
+
+    @Override
+    public void onTextMessageReceived(TextMessage textMessage) {
+        // Text message received
+    }
+
+    @Override
+    public void onMessageReactionAdded(ReactionEvent reactionEvent) {
+        // Reaction added
+    }
+});
+
+// Remove when done
+CometChatMessageEvents.removeListener("unique-tag");
+```
+
+**Kotlin:**
+```kotlin
+CometChatMessageEvents.addListener("unique-tag", object : CometChatMessageEvents() {
+    override fun ccMessageSent(baseMessage: BaseMessage, status: Int) {
+        // Message sent
+    }
+
+    override fun onTextMessageReceived(textMessage: TextMessage) {
+        // Text message received
+    }
+
+    override fun onMessageReactionAdded(reactionEvent: ReactionEvent) {
+        // Reaction added
+    }
+})
+
+// Remove when done
+CometChatMessageEvents.removeListener("unique-tag")
+```
+
+### CometChatUserEvents
+
+```java
+CometChatUserEvents.addUserListener("unique-tag", new CometChatUserEvents() {
+    @Override
+    public void ccUserBlocked(User user) { }
+
+    @Override
+    public void ccUserUnblocked(User user) { }
+});
+```
+
+### CometChatGroupEvents
+
+```java
+CometChatGroupEvents.addGroupListener("unique-tag", new CometChatGroupEvents() {
+    @Override
+    public void ccGroupCreated(Group group) { }
+    @Override
+    public void ccGroupDeleted(Group group) { }
+    @Override
+    public void ccGroupMemberJoined(User joinedUser, Group joinedGroup) { }
+    @Override
+    public void ccGroupMemberKicked(Action action, User kicked, User kickedBy, Group from) { }
+    @Override
+    public void ccGroupMemberBanned(Action action, User banned, User bannedBy, Group from) { }
+});
+```
+
+### CometChatCallEvents
+
+```java
+CometChatCallEvents.addListener("unique-tag", new CometChatCallEvents() {
+    @Override
+    public void ccOutgoingCall(Call call) { }
+    @Override
+    public void ccCallAccepted(Call call) { }
+    @Override
+    public void ccCallRejected(Call call) { }
+    @Override
+    public void ccCallEnded(Call call) { }
+});
+```
+
+---
+
+## 5. Custom view slots on components
+
+Most components support custom view injection via `Function3<Context, User, Group, View>`:
+
+```java
+CometChatMessageHeader header = findViewById(R.id.header);
+header.setSubtitleView((context, user, group) -> {
+    TextView subtitle = new TextView(context);
+    if (user != null) {
+        subtitle.setText(user.getStatus().equals("online") ? "Active now" : "Offline");
+    }
+    return subtitle;
+});
+```
+
+---
+
+## Hard rules
+
+- **Always extend `DataSourceDecorator`, never implement `DataSource` directly.** The decorator preserves existing behavior.
+- **Register `ChatConfigurator.enable()` AFTER `CometChatUIKit.init()` succeeds.** The configurator resets on init.
+- **Always remove event listeners when the Activity/Fragment is destroyed.** Use `onDestroy()` or `onDestroyView()`.
+- **Template view slots use `MessagesViewHolderListener`.** Implement both `createView()` and `bindView()`.

package/skills/cometchat-android-v5-extensions/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: cometchat-android-v5-extensions
+description: "Extension architecture for CometChat Android — ExtensionsDataSource, decorators, built-in extensions, and how to create custom extensions."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android extensions datasource decorator polls stickers collaborative"
+---
+
+> **Companion skills:** `cometchat-android-v5-customization` covers DataSource decorators;
+> `cometchat-android-v5-features` covers the feature catalog.
+
+## Purpose
+
+This skill covers the CometChat extension architecture — how extensions plug into the UI Kit, the built-in extensions, and how to create custom ones.
+
+---
+
+## Use this skill when
+
+- "How do extensions work?"
+- "How do I add a custom extension?"
+- "How do I disable an extension?"
+- Working with `ExtensionsDataSource` or `ExtensionDecorator`
+
+## Do not use this skill when
+
+- Enabling a backend extension or AI feature → use `cometchat-android-v5-features` (which routes to `cometchat apply-feature <id> --app-id <X>`)
+- Writing custom message templates → use `cometchat-android-v5-customization`
+
+---
+
+## 1. Extension architecture
+
+Extensions are split into two class types:
+
+- **Registrar** classes (e.g. `PollsExtension`, `StickerExtension`) — extend `ExtensionsDataSource`. These are what you pass to `setExtensions(...)` to enable a built-in extension.
+- **Decorator** classes (e.g. `PollsExtensionDecorator`, `StickerExtensionDecorator`) — extend `DataSourceDecorator`. These are the runtime decorators that wrap the active `DataSource` chain. The kit creates them internally; you don't construct them directly.
+
+```
+ChatConfigurator.getDataSource()
+    └── SmartRepliesExtensionDecorator   (created by SmartRepliesExtension)
+        └── PollsExtensionDecorator      (created by PollsExtension)
+            └── StickerExtensionDecorator (created by StickerExtension)
+                └── MessagesDataSource (base)
+```
+
+## 2. Built-in extensions
+
+| Extension | Package | What it adds |
+|---|---|---|
+| Polls | `com.cometchat.chatuikit.extensions.polls` | Poll creation and voting in messages |
+| Stickers | `com.cometchat.chatuikit.extensions.sticker` | Sticker keyboard and sticker bubbles |
+| Collaborative Document | `com.cometchat.chatuikit.extensions.collaborative` | Shared document editing |
+| Collaborative Whiteboard | `com.cometchat.chatuikit.extensions.collaborative` | Shared whiteboard |
+| Smart Replies | `com.cometchat.chatuikit.extensions.smartreplies` | AI-powered reply suggestions |
+| Message Translation | `com.cometchat.chatuikit.extensions.messagetranslation` | Translate messages |
+| Text Moderation | `com.cometchat.chatuikit.extensions.textmoderation` | Profanity filtering |
+| Thumbnail Generation | `com.cometchat.chatuikit.extensions.thumbnailgeneration` | Image thumbnails |
+
+## 3. Enabling/disabling extensions
+
+Extensions are enabled by default. To customize which extensions are active, pass a custom list to `UIKitSettingsBuilder`:
+
+```java
+List<ExtensionsDataSource> extensions = new ArrayList<>();
+extensions.add(new PollsExtension());            // registrar, NOT PollsExtensionDecorator
+extensions.add(new StickerExtension());         // registrar, NOT StickerExtensionDecorator
+extensions.add(new SmartRepliesExtension());
+// Omit extensions you don't want
+
+UIKitSettings settings = new UIKitSettings.UIKitSettingsBuilder()
+    .setAppId(APP_ID)
+    .setRegion(REGION)
+    .setAuthKey(AUTH_KEY)
+    .setExtensions(extensions)
+    .build();
+```
+
+> **Why not `PollsExtensionDecorator`?** `*ExtensionDecorator` extends `DataSourceDecorator`, not `ExtensionsDataSource` — so it won't compile when added to a `List<ExtensionsDataSource>`. The kit's runtime decorator chain is built by the registrar's `enable()` method internally; you don't add decorators directly.
+
+## 4. Creating a custom extension
+
+A custom extension has TWO classes:
+
+1. A **registrar** that extends `ExtensionsDataSource` (gets added to `setExtensions(...)`)
+2. A **decorator** that extends `DataSourceDecorator` (created by the registrar via `ChatConfigurator.enable(...)`)
+
+```java
+// 1. Decorator — extends DataSourceDecorator, overrides per-message behavior
+public class MyExtensionDecorator extends DataSourceDecorator {
+    public MyExtensionDecorator(DataSource dataSource) {
+        super(dataSource);
+    }
+    // Override methods to add custom behavior
+}
+
+// 2. Registrar — extends ExtensionsDataSource, exposes getExtensionId() and enable()
+public class MyExtension extends ExtensionsDataSource {
+    @Override
+    public String getExtensionId() {
+        return "my-custom-extension";
+    }
+
+    @Override
+    public void enable() {
+        ChatConfigurator.enable(dataSource -> new MyExtensionDecorator(dataSource));
+    }
+}
+
+// Then add the registrar to UIKitSettings:
+extensions.add(new MyExtension());
+```
+
+---
+
+## Hard rules
+
+- **Two classes per extension.** A registrar (`ExtensionsDataSource`, holds `getExtensionId()` + `enable()`) and a decorator (`DataSourceDecorator`, holds the per-message override). `setExtensions(...)` wants registrars; the chain builds decorators automatically.
+- **Register after init.** `ChatConfigurator.enable()` must be called after `CometChatUIKit.init()` succeeds.
+- **Backend extension toggle still applies.** Even if an extension is registered client-side, it needs to be enabled on the app's backend. Use `cometchat apply-feature <id> --app-id <X>` (the CLI hits the dashboard API). For dashboard-only extensions (Giphy / Stipop / Tenor / Chatwoot / Intercom — those needing third-party API keys), the user has to enter the third-party config in the dashboard manually.

package/skills/cometchat-android-v5-features/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: cometchat-android-v5-features
+description: "Add features (calls, reactions, polls, file sharing, AI, etc.) to an already-integrated CometChat project. Routes to the right sub-flow based on feature type."
+license: "MIT"
+compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat android features extensions calls reactions polls ai-features"
+---
+
+> **Companion skills:** `cometchat-android-v5-core` covers initialization;
+> `cometchat-android-v5-customization` covers deeper component customization;
+> `cometchat-android-v5-extensions` covers the extension architecture.
+
+## Purpose
+
+This skill teaches how CometChat features are structured and what work is required to enable each one. Most features require zero code — they are either already built into the UI Kit, toggled via the `cometchat apply-feature` CLI (extensions + AI features), or activated by adding a dependency (calls).
+
+---
+
+## Use this skill when
+
+- "Add reactions to my chat"
+- "Add video calling"
+- "Enable polls"
+- "Add file sharing"
+- "Enable smart replies"
+
+## Do not use this skill when
+
+- Customizing how a feature looks → use `cometchat-android-v5-customization`
+- Setting up the initial integration → use `cometchat-android-v5-core`
+
+---
+
+## 1. Feature types
+
+| Type | What it means | Action required |
+|---|---|---|
+| Type 1 — Default | Built into the UI Kit at compile time | None — already there |
+| Type 2a — Extension | Backend extension, pure boolean toggle | `cometchat apply-feature <id> --app-id <X>` (CLI hits dashboard API) |
+| Type 2b — AI feature | Backend AI feature requiring an OpenAI key | `cometchat apply-feature <id> --app-id <X> --openai-key sk-...` |
+| Type 2c — Dashboard-only | Third-party API key / multi-field config (Giphy, Stipop, Tenor, Chatwoot, Intercom) | Open https://app.cometchat.com → Extensions → configure |
+| Type 3 — Package-install | Requires a separate SDK dependency | Add Gradle dependency |
+| Type 4 — Component-toggle | Hide/show via `setHide*` / `disable*` methods on the relevant component | Call the setter on the component instance (see catalog) |
+
+---
+
+## 2. Type 1 — Default features (already enabled)
+
+| Feature | Component | Notes |
+|---|---|---|
+| Text messaging | `CometChatMessageComposer` + `CometChatMessageList` | Core feature |
+| Media sharing (image/video/audio/file) | `CometChatMessageComposer` | Attachment button |
+| Read receipts | `CometChatMessageList` | `setReceiptsVisibility()` |
+| Typing indicators | `CometChatMessageList` + `CometChatConversations` | Auto-enabled |
+| User presence (online/offline) | `CometChatConversations`, `CometChatUsers` | Requires `subscribePresenceForAllUsers()` in init |
+| Reactions | `CometChatMessageList` | Long-press message → react |
+| Mentions (@user, @all) | `CometChatMessageComposer` | Type `@` to trigger |
+| Threaded conversations | `CometChatMessageList` | `setReplyInThreadOptionVisibility()` |
+| Quoted replies | `CometChatMessageList` | Swipe to reply |
+| Edit/delete messages | `CometChatMessageList` | Long-press options |
+| Group chat | All components | Use `setGroup()` instead of `setUser()` |
+| Report message | `CometChatMessageList` | Long-press → Report |
+| Search | `CometChatSearch` | Standalone component |
+
+---
+
+## 3. Type 2 — Backend toggle features (no code needed)
+
+Android projects don't run `cometchat apply`, so call the CLI in stateless mode with `--app-id`:
+
+```bash
+# Pure boolean extensions:
+cometchat apply-feature polls --app-id <your-app-id>
+cometchat apply-feature stickers --app-id <your-app-id>
+
+# AI features (require OpenAI key):
+cometchat apply-feature smart-replies --app-id <your-app-id> --openai-key sk-...
+cometchat apply-feature conversation-summary --app-id <your-app-id>
+cometchat apply-feature conversation-starter --app-id <your-app-id>
+```
+
+Requires `cometchat auth login` once per machine.
+
+**Extensions (CLI-toggleable — pure boolean):**
+- User Engagement: Polls, Message Translation, Reminders
+- Collaboration: Collaborative Document, Collaborative Whiteboard
+- Security: Disappearing Messages, E2E Encryption (Enterprise)
+- Moderation: Profanity Filter, Image Moderation, Data Masking, Sentiment Analysis, XSS Filter
+
+**AI Features (CLI-toggleable — needs `--openai-key`):**
+Conversation Starter, Conversation Summary, Smart Reply
+
+**Dashboard-only (third-party config — open https://app.cometchat.com → Extensions):**
+Stickers (Stipop), Giphy, Tenor, Chatwoot, Intercom — these require API keys / webhooks the user must enter manually.
+
+---
+
+## 4. Type 3 — Package-install features
+
+### Voice/Video Calling
+
+Add the calling SDK:
+
+```groovy
+implementation 'com.cometchat:calls-sdk-android:4.+'
+```
+
+The UI Kit auto-detects the calling SDK and enables call buttons in `CometChatMessageHeader`. No additional code needed — `CometChatIncomingCall`, `CometChatOutgoingCall`, and `CometChatOngoingCall` activate automatically.
+
+Configure call buttons visibility:
+
+```java
+CometChatMessageHeader header = findViewById(R.id.header);
+header.setVoiceCallButtonVisibility(View.VISIBLE);
+header.setVideoCallButtonVisibility(View.VISIBLE);
+```
+
+---
+
+## Hard rules
+
+- **Don't write code for Type 1 features.** They're already there. Tell the user where to find them.
+- **Don't write code for Type 2a/2b features.** Run `cometchat apply-feature <id> --app-id <X>` (extension) or `... --openai-key sk-...` (ai-feature). The CLI flips the dashboard toggle via API. Never tell the user to "open the dashboard and toggle X" for an extension or ai-feature — that's what the CLI does.
+- **For Type 2c (dashboard-only) features**, the CLI cannot automate (third-party keys / multi-field config). Walk the user through the dashboard path returned by `cometchat apply-feature <id>`'s `manual-action-required` response.
+- **For Type 3 (calls), just add the Gradle dependency.** The UI Kit handles the rest.
+- **Always run `cometchat apply-feature <id>` first** for extensions and AI features. If the user reports a "missing feature," it's almost always an unflipped toggle the CLI can fix in one call.