@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-ios/SKILL.md

@@ -1,325 +0,0 @@
----
-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"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat dispatcher entry ios swift uikit swiftui chat messaging"
----
-
-> **Ground truth:** `CometChatUIKitSwift ~> 5` (+ `CometChatCallsSDK ~> 5`) — Pods/SPM `.swiftinterface` + `ui-kit/ios`. **Official docs:** https://www.cometchat.com/docs/ui-kit/ios/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
-
-## Use this skill when
-
-The user wants to add CometChat to any iOS project. Trigger phrases:
-
-- `/cometchat` (or invoke the cometchat-ios skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
-- "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 (CometChatSDK floor is iOS 11)
-- **iOS 16+ required if you use calling** — `CometChatCallsSDK` 5.x has a deployment target of iOS 16.0; a project targeting iOS 13 will fail to link the Calls SDK
-- Swift 5.0+ required
-- Xcode 14+ recommended
-
-### Step 2 — Set up credentials (onboarding)
-
-**Ask the user for their CometChat credentials:**
-
-Ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but all support this structured form):
-- **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?"
-
-Ask the user (preserve the structured shape — `question`/`header`/`multiSelect`/`options[].label`/`options[].description`):
-- **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
-
-Ask the user (preserve the structured shape — `question`/`header`/`options[].label`/`options[].description`):
-- **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

package/skills/cometchat-ios-calls/references/add-calls-to-existing-chat.md

@@ -1,181 +0,0 @@
-# Adding calls to an existing chat integration (iOS)
-
-You have `CometChatUIKitSwift` working. This guide adds `CometChatCallsSDK` plus PushKit + CallKit + the seven hard rules.
-
-**Read first:** `cometchat-ios-calls/SKILL.md` — seven hard rules (init order, IncomingCall mount, hangup teardown, VoIP push, etc.).
-
----
-
-## Step 1 — Install Calls SDK
-
-**SwiftPM:**
-- File → Add Packages → `https://github.com/cometchat/calls-sdk-ios` → version `5.0.0+`
-- Add `CometChatCallsSDK` to your app target
-
-**CocoaPods:**
-```ruby
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-```bash
-pod install --repo-update
-```
-
----
-
-## Step 2 — Add capabilities + Info.plist entries
-
-**Xcode → target → Signing & Capabilities:**
-- Push Notifications
-- Background Modes → check Audio, AirPlay, and Picture in Picture + Voice over IP + Remote notifications
-
-**Info.plist:**
-```xml
-<key>UIBackgroundModes</key>
-<array>
-  <string>audio</string>
-  <string>voip</string>
-  <string>remote-notification</string>
-</array>
-<key>NSCameraUsageDescription</key>
-<string>Camera access is required for video calls.</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone access is required for calls.</string>
-```
-
----
-
-## Step 3 — Init order: chat → calls
-
-Wherever you currently call `CometChatUIKit.init(uikitSettings:)`, append the calls init:
-
-```swift
-import CometChatSDK
-import CometChatCallsSDK
-import CometChatUIKitSwift
-
-// Existing chat init
-CometChatUIKit.init(uikitSettings: chatSettings) { result in
-  switch result {
-  case .success:
-    // NEW: Calls init AFTER chat init succeeded.
-    // File-based init (CometChatCallsSDK >= 5.0.2 — requires iOS 15.1+ deployment
-    // target or CocoaPods silently resolves 5.0.1 without this API):
-    // reads the same bundled cometchat-settings.json the chat side uses and
-    // attributes the integration as ai-agent — see cometchat-ios-calls SKILL.md §2.
-    CometChatCalls.initFromSettings(onSuccess: { _ in
-      // calls ready
-    }, onError: { error in
-      print("CometChatCalls init failed: \(error?.errorDescription ?? "")")
-    })
-    // Pre-5.0.2 fallback: CallAppSettingsBuilder().setAppId(...).setRegion(...).build()
-    // passed to CometChatCalls.init(callsAppSettings:onSuccess:onError:).
-  case .onError(let error):
-    print(error)
-  }
-}
-```
-
----
-
-## Step 4 — Login
-
-Log in with the Chat SDK only. **There is no `CometChatCalls.login` and no `CometChat.loginAsync`** — the Calls SDK has no separate login step; it authenticates per call session via `generateToken`.
-
-```swift
-CometChat.login(UID: uid, authKey: authKey, onSuccess: { user in
-  // logged in — that's it. Do NOT call CometChatCalls.login (doesn't exist).
-  // When a call starts, call CometChatCalls.generateToken(authToken:sessionID:)
-  // with CometChat.getUserAuthToken() (User has no `authToken` property).
-}, onError: { error in /* surface */ })
-```
-
-If you use server-minted auth tokens (recommended), use the `CometChat.login(UID:authToken:...)` overload instead of `authKey`.
-
----
-
-## Step 5 — Mount IncomingCall at root
-
-In SwiftUI:
-
-```swift
-@main
-struct YourApp: App {
-  var body: some Scene {
-    WindowGroup {
-      RootView()
-        .overlay(alignment: .top) {
-          CometChatIncomingCall()
-        }
-    }
-  }
-}
-```
-
-In UIKit:
-- Make a `RootViewController` that holds your existing app + the `CometChatIncomingCallView`
-- Or use `UIWindow.rootViewController` swap pattern when an incoming call arrives
-
----
-
-## Step 6 — PushKit + CallKit registration
-
-Implement `PKPushRegistryDelegate` (see `cometchat-ios-calls/references/server-apns-pushkit.md`):
-
-```swift
-class VoipPushHandler: NSObject, PKPushRegistryDelegate {
-  let registry = PKPushRegistry(queue: .main)
-  let callProvider: CXProvider
-
-  func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
-    let token = credentials.token.map { String(format: "%02x", $0) }.joined()
-    Task { try await api.registerVoipToken(uid: currentUid, token: token) }
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
-    // Report to CallKit IMMEDIATELY
-    let update = CXCallUpdate()
-    let dict = payload.dictionaryPayload
-    update.remoteHandle = CXHandle(type: .generic, value: dict["callerUid"] as? String ?? "Unknown")
-    update.localizedCallerName = dict["callerName"] as? String ?? "Unknown"
-    update.hasVideo = (dict["callType"] as? String) == "video"
-    callProvider.reportNewIncomingCall(with: UUID(), update: update) { _ in completion() }
-  }
-}
-```
-
-Init this handler from your `AppDelegate.didFinishLaunchingWithOptions`.
-
----
-
-## Step 7 — Hangup teardown
-
-```swift
-func endCall(sessionId: String) {
-  CometChatCalls.endSession()   // Calls SDK — EXISTS (not leaveSession)
-  CometChat.endCall(sessionID: sessionId, onSuccess: { _ in }, onError: { _ in })
-  callProvider.reportCall(with: callUUID, endedAt: nil, reason: .remoteEnded)
-}
-```
-
----
-
-## Verification checklist
-
-- [ ] `CometChatCallsSDK` in SwiftPM/CocoaPods
-- [ ] Background Modes capability + Info.plist UIBackgroundModes (audio + voip + remote-notification)
-- [ ] NSCameraUsageDescription + NSMicrophoneUsageDescription
-- [ ] Calls init runs AFTER chat init succeeds
-- [ ] NO `CometChatCalls.login` (doesn't exist) — Calls auth is per-session via `generateToken`
-- [ ] `CometChatIncomingCall` mounted at root (SwiftUI overlay or UIKit window-root)
-- [ ] PushKit registry initialized + reports to CallKit within 5s
-- [ ] Hangup teardown ends both SDK + CallKit + chat-side call record
-- [ ] Real-device smoke: backgrounded incoming call rings on lock screen
-- [ ] Run `cometchat verify --calls` — should pass
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/add-calls-to-existing-chat.md` — canonical (no native modules)
-- `cometchat-ios-calls/SKILL.md` — seven hard rules
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — server-side PushKit

package/skills/cometchat-ios-calls/references/audio-modes-and-controls.md

@@ -1,45 +0,0 @@
-# iOS — Audio Modes + Custom Control Panel
-
-Verified against `CometChatCallsSDK` 5.x (`callssdk.swiftinterface`).
-
-## 1. Audio modes (speaker / earpiece / Bluetooth)
-
-The SDK reports the available audio routes via the `CallsEventsDelegate` as typed `CallAudioMode` objects (swiftinterface:133 — `mode: String`, `isSelected: Bool`), and lets you switch programmatically by passing a `CallAudioMode`.
-
-```swift
-import CometChatCallsSDK
-
-// Observe available routes + current selection (typed form).
-// swiftinterface:44 onAudioModeChanged(mode: [CallAudioMode])
-func onAudioModeChanged(mode: [CallAudioMode]) {
-    self.audioRoutes = mode   // each has .mode (e.g. "SPEAKER") and .isSelected
-}
-
-// Switch route with a typed CallAudioMode — the current setter.
-// swiftinterface:234 CometChatCalls.setAudioMode(_ audioMode: CallAudioMode)
-CometChatCalls.setAudioMode(CallAudioMode(mode: "SPEAKER", isSelected: true))
-```
-
-Note the kit's default in-call UI already shows an audio-mode button; you only need the above for a **custom** control surface (or to drive routing yourself).
-
-Verified against `CometChatCallsSDK` swiftinterface: the typed `CallsEventsDelegate.onAudioModeChanged(mode: [CallAudioMode])` (swiftinterface:44) and `CometChatCalls.setAudioMode(_ audioMode: CallAudioMode)` (swiftinterface:234) are the CURRENT API. The string forms — `onAudioModeChanged(audioModeList: NSArray)` (swiftinterface:43) and `setAudioMode(mode: String)` (swiftinterface:235) — are DEPRECATED.
-
-## 2. Custom control panel (hide built-in buttons)
-
-There is no separate "panel" object — you compose a custom control bar by **disabling the kit's default buttons** on the `CallSettingsBuilder`, then rendering your own controls (wired to `audioMuted(_:)`, `videoPaused(_:)`, `switchCamera()`, `endSession()`, etc. from the main skill):
-
-```swift
-let settings = CallSettingsBuilder()
-  .setEndCallButtonDisable(true)
-  .setMuteAudioButtonDisable(true)
-  .setPauseVideoButtonDisable(true)
-  .setSwitchCameraButtonDisable(true)
-  .setAudioModeButtonDisable(true)
-  .setShowRecordingButton(false)
-  .build()
-// then overlay your own SwiftUI/UIKit control bar on the call container
-```
-
-Verified (on `CallSettingsBuilder`): `setEndCallButtonDisable`, `setMuteAudioButtonDisable`, `setPauseVideoButtonDisable`, `setSwitchCameraButtonDisable`, `setAudioModeButtonDisable`, `setShowRecordingButton` — all `(Bool) -> Self`.
-
-> **Not supported on iOS** (no SDK symbol — do not author): Virtual Background, and local screen-share **initiation** (receive-only). See the main skill's resolution note.