@cometchat/skills 3.1.0 → 4.0.0

package/skills/cometchat-ios-core/SKILL.md

@@ -0,0 +1,822 @@
+---
+name: cometchat-ios-core
+description: "Shared rules for CometChat iOS UI Kit v5. Always loaded alongside placement skills. Read this first."
+license: "MIT"
+compatibility: "iOS 13+; Swift 5.0+; CometChatUIKitSwift ^5; CometChatSDK ^4"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "chat cometchat ios swift core rules initialization patterns"
+---
+
+## Purpose
+
+This is the foundational skill for every CometChat iOS UI Kit v5 integration. It teaches HOW CometChat works on iOS — initialization, login, the manager pattern, and anti-patterns — so you can write project-appropriate code instead of relying on templates.
+
+**Read this skill first, before any placement or component skill.**
+
+---
+
+## 1. Installation
+
+### 0. First — confirm a dependency manifest exists (or create one)
+
+A freshly-created Xcode project (`File → New → App` from the GUI) ships **no `Podfile`, no `Package.swift`, and no Swift Package Manager refs in `*.xcodeproj/project.pbxproj`**. Before touching any of the integration code below, you MUST establish a dependency-management mechanism — otherwise `import CometChatUIKitSwift` will hit `Unable to resolve module dependency: 'CometChatSDK'` at the first build attempt and the entire integration is dead on arrival.
+
+**Detection:**
+
+```bash
+ls Podfile Package.swift 2>/dev/null
+grep -l "XCRemoteSwiftPackageReference\|repositoryURL.*cometchat" *.xcodeproj/project.pbxproj 2>/dev/null
+```
+
+If all three return empty → **fresh Xcode project, no dep manager**. Pick one and set it up before continuing:
+
+**Option A — CocoaPods (most common, easiest to script):**
+
+```bash
+cd <project-root>
+cat > Podfile <<'POD'
+platform :ios, '13.0'
+use_frameworks!
+
+target 'YourAppTargetName' do
+  pod 'CometChatUIKitSwift', '~> 5.1'
+end
+
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    target.build_configurations.each do |config|
+      config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
+    end
+  end
+end
+POD
+pod install
+```
+
+After `pod install`, work from `YourApp.xcworkspace` (NOT `.xcodeproj`) — CocoaPods rewires the workspace to include the Pods project.
+
+**Option B — Swift Package Manager (no Podfile, no `.xcworkspace`):**
+
+The user must add the package via Xcode's GUI (the SPM dependency lives in `*.xcodeproj/project.pbxproj` and there's no clean CLI tooling to edit that file safely). Print these instructions verbatim:
+
+> 1. Open `<YourApp>.xcodeproj` in Xcode
+> 2. **File → Add Package Dependencies…**
+> 3. Paste URL: `https://github.com/cometchat/cometchat-uikit-ios`
+> 4. **Add Package** → keep "Up to Next Major Version" defaults → **Add Package** again
+> 5. Confirm `CometChatUIKitSwift` appears under your app target's *Frameworks, Libraries, and Embedded Content*
+
+**Then verify the package landed:**
+
+```bash
+grep -E "cometchat-uikit-ios|CometChatUIKitSwift" *.xcodeproj/project.pbxproj | head -2
+```
+
+If grep returns matches, the SPM dep is in. If it doesn't, the user didn't complete step 4 in Xcode — surface that explicitly and stop until they have.
+
+**HARD STOP if neither option is in place.** Do not write `import CometChatUIKitSwift` into any Swift file until either `pod install` completes successfully or the SPM grep above returns matches. Skipping this step produces an integration that compiles only after the user does extra setup work — a worse outcome than asking them up-front.
+
+### CocoaPods (full reference — only if you skipped Option A above)
+
+Add to your `Podfile`:
+
+```ruby
+platform :ios, '13.0'
+use_frameworks!
+
+target 'YourApp' do
+  pod 'CometChatUIKitSwift', '~> 5.1'
+end
+```
+
+Then run:
+```bash
+pod install
+```
+
+**Important: Disable User Script Sandboxing (Xcode 15+)**
+
+After running `pod install`, you must disable user script sandboxing in your project's Build Settings:
+
+1. Open your `.xcworkspace` file
+2. Select your app target
+3. Go to **Build Settings**
+4. Search for "User Script Sandboxing"
+5. Set **ENABLE_USER_SCRIPT_SANDBOXING** to **No**
+
+Or add this to your `Podfile` to do it automatically:
+
+```ruby
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    target.build_configurations.each do |config|
+      config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
+    end
+  end
+end
+```
+
+### Swift Package Manager
+
+Add the package URL in Xcode (File → Add Package Dependencies):
+
+**CometChat UI Kit (includes SDK):**
+```
+https://github.com/cometchat/cometchat-uikit-ios
+```
+
+**CometChat SDK only (if needed separately):**
+```
+https://github.com/cometchat/chat-sdk-ios
+```
+
+**CometChat Calls SDK (for voice/video calls):**
+```
+https://github.com/cometchat/cometchat-calls-sdk-ios
+```
+
+Or add to `Package.swift`:
+```swift
+dependencies: [
+    .package(url: "https://github.com/cometchat/cometchat-uikit-ios", from: "5.0.0"),
+    // Optional: Add calls SDK for voice/video
+    // .package(url: "https://github.com/cometchat/cometchat-calls-sdk-ios", from: "4.0.0")
+]
+```
+
+### GitHub Repositories
+
+| Package | Repository | Description |
+|---------|------------|-------------|
+| UI Kit | https://github.com/cometchat/cometchat-uikit-ios | Ready-to-use UI components |
+| Chat SDK | https://github.com/cometchat/chat-sdk-ios | Core messaging SDK |
+| Calls SDK | https://github.com/cometchat/cometchat-calls-sdk-ios | Voice & video calling |
+| Sample App | https://github.com/cometchat/cometchat-sample-app-ios | Sample implementation |
+
+---
+
+## 2. Initialization
+
+CometChat must be initialized exactly once before any UI component is used. Initialization is asynchronous and must complete fully before mounting any `CometChat*` view controller.
+
+### UIKitSettings Builder
+
+```swift
+import CometChatUIKitSwift
+
+let uiKitSettings = UIKitSettings()
+    .set(appID: "YOUR_APP_ID")
+    .set(authKey: "YOUR_AUTH_KEY")  // Required for dev mode
+    .set(region: "us")               // "us", "eu", or "in"
+    .subscribePresenceForAllUsers()  // Enable online/offline indicators
+    .build()
+```
+
+### Init must happen once
+
+Use a singleton manager to prevent double-init:
+
+```swift
+import CometChatUIKitSwift
+import CometChatSDK
+
+final class CometChatManager {
+    static let shared = CometChatManager()
+    
+    private var isInitialized = false
+    private var initializationError: Error?
+    
+    private init() {}
+    
+    func initialize(
+        appID: String,
+        authKey: String,
+        region: String,
+        completion: @escaping (Result<Bool, Error>) -> Void
+    ) {
+        guard !isInitialized else {
+            completion(.success(true))
+            return
+        }
+        
+        let uiKitSettings = UIKitSettings()
+            .set(appID: appID)
+            .set(authKey: authKey)
+            .set(region: region)
+            .subscribePresenceForAllUsers()
+            .build()
+        
+        CometChatUIKit(uiKitSettings: uiKitSettings) { result in
+            switch result {
+            case .success(let success):
+                self.isInitialized = success
+                completion(.success(success))
+            case .failure(let error):
+                self.initializationError = error
+                completion(.failure(error))
+            }
+        }
+    }
+}
+```
+
+### Init in AppDelegate (UIKit apps)
+
+```swift
+import UIKit
+import CometChatUIKitSwift
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        
+        CometChatManager.shared.initialize(
+            appID: "YOUR_APP_ID",
+            authKey: "YOUR_AUTH_KEY",
+            region: "us"
+        ) { result in
+            switch result {
+            case .success:
+                print("CometChat initialized successfully")
+            case .failure(let error):
+                print("CometChat initialization failed: \(error)")
+            }
+        }
+        
+        return true
+    }
+}
+```
+
+### Init in App struct (SwiftUI apps)
+
+```swift
+import SwiftUI
+import CometChatUIKitSwift
+
+@main
+struct YourApp: App {
+    
+    init() {
+        CometChatManager.shared.initialize(
+            appID: "YOUR_APP_ID",
+            authKey: "YOUR_AUTH_KEY",
+            region: "us"
+        ) { result in
+            switch result {
+            case .success:
+                print("CometChat initialized successfully")
+            case .failure(let error):
+                print("CometChat initialization failed: \(error)")
+            }
+        }
+    }
+    
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+---
+
+## 3. Login
+
+### Development mode
+
+Use `CometChatUIKit.login(uid:)` with a test UID. Every new CometChat app comes with five pre-created test users: `cometchat-uid-1` through `cometchat-uid-5`.
+
+**Important:** The login callback uses `.success` and `.onError` cases, NOT Swift's standard `Result` type.
+
+```swift
+CometChatUIKit.login(uid: "cometchat-uid-1") { result in
+    switch result {
+    case .success(let user):
+        print("Logged in as: \(user.name ?? "")")
+        // Proceed to chat UI
+    case .onError(let error):
+        print("Login failed: \(error.errorDescription)")
+    @unknown default:
+        break
+    }
+}
+```
+
+### Production mode
+
+Use `CometChatUIKit.login(authToken:)` with a token obtained from your backend:
+
+```swift
+CometChatUIKit.login(authToken: authToken) { result in
+    switch result {
+    case .success(let user):
+        print("Logged in as: \(user.name ?? "")")
+    case .onError(let error):
+        print("Login failed: \(error.errorDescription)")
+    @unknown default:
+        break
+    }
+}
+```
+
+### Getting the current logged-in user
+
+```swift
+// Synchronous — use when you know init is complete
+if let currentUser = CometChatUIKit.getLoggedInUser() {
+    print("Logged in as: \(currentUser.name ?? "")")
+}
+```
+
+### Logout
+
+```swift
+if let currentUser = CometChat.getLoggedInUser() {
+    CometChatUIKit.logout(user: currentUser) { result in
+        switch result {
+        case .success:
+            print("Logged out successfully")
+        case .onError(let error):
+            print("Logout failed: \(error.errorDescription)")
+        @unknown default:
+            break
+        }
+    }
+}
+```
+
+---
+
+## 3.1 Error Handling
+
+CometChat uses `CometChatException` for errors. **Important:** Use `errorDescription` property, NOT `localizedDescription`.
+
+### CometChatException Properties
+
+```swift
+// CometChatException has these properties:
+error.errorCode        // String - error code like "ERR_UID_NOT_FOUND"
+error.errorDescription // String - human-readable description
+error.details          // [String: Any]? - additional details
+```
+
+### Correct Error Handling
+
+```swift
+CometChatUIKit.login(uid: "user-123") { result in
+    switch result {
+    case .success(let user):
+        print("Logged in: \(user.name ?? "")")
+    case .onError(let error):
+        print("Error: \(error.errorDescription)")
+        print("Code: \(error.errorCode)")
+    }
+}
+```
+
+### Error Handling in Closures
+
+```swift
+// For onError closures where error might be optional:
+CometChat.getUser(UID: "user-123") { user in
+    print("User: \(user?.name ?? "")")
+} onError: { error in
+    // error is CometChatException? (optional)
+    print("Error: \(error?.errorDescription ?? "Unknown error")")
+}
+
+// For ApiStatus enum results:
+CometChatUIKit.create(user: newUser) { result in
+    switch result {
+    case .success(let user):
+        print("Created: \(user.name ?? "")")
+    case .onError(let error):
+        // error is CometChatException (non-optional)
+        print("Error: \(error.errorDescription)")
+    }
+}
+```
+
+### Common Error Codes
+
+| Code | Description |
+|---|---|
+| `ERR_UID_NOT_FOUND` | User doesn't exist |
+| `ERR_ALREADY_LOGGED_IN` | User already logged in |
+| `ERR_NOT_LOGGED_IN` | No active session |
+| `AUTH_ERR_AUTH_TOKEN_NOT_FOUND` | Invalid auth token |
+| `ERR_INVALID_APP_ID` | Wrong App ID |
+| `ERR_INVALID_API_KEY` | Wrong API/Auth Key |
+
+---
+
+## 4. Credentials Management
+
+### Using a Constants file (Development)
+
+```swift
+// Constants.swift
+struct CometChatConstants {
+    static let appID = "YOUR_APP_ID"
+    static let authKey = "YOUR_AUTH_KEY"
+    static let region = "us"
+}
+```
+
+**Important:** Add `Constants.swift` to `.gitignore` for production apps.
+
+### Using Info.plist
+
+Add keys to your `Info.plist`:
+```xml
+<key>CometChatAppID</key>
+<string>YOUR_APP_ID</string>
+<key>CometChatAuthKey</key>
+<string>YOUR_AUTH_KEY</string>
+<key>CometChatRegion</key>
+<string>us</string>
+```
+
+Read them in code:
+```swift
+guard let appID = Bundle.main.object(forInfoDictionaryKey: "CometChatAppID") as? String,
+      let authKey = Bundle.main.object(forInfoDictionaryKey: "CometChatAuthKey") as? String,
+      let region = Bundle.main.object(forInfoDictionaryKey: "CometChatRegion") as? String else {
+    fatalError("CometChat credentials not found in Info.plist")
+}
+```
+
+### Using xcconfig files (Recommended for production)
+
+Create `Debug.xcconfig` and `Release.xcconfig`:
+```
+// Debug.xcconfig
+COMETCHAT_APP_ID = your_app_id
+COMETCHAT_AUTH_KEY = your_auth_key
+COMETCHAT_REGION = us
+```
+
+Reference in `Info.plist`:
+```xml
+<key>CometChatAppID</key>
+<string>$(COMETCHAT_APP_ID)</string>
+```
+
+---
+
+## 5. The Manager Pattern
+
+The recommended pattern for iOS is a singleton manager that handles initialization, login state, and provides a clean API for the rest of the app.
+
+### Complete CometChatManager
+
+**Important:** `CometChatException` does NOT conform to Swift's `Error` protocol. Use `CometChatException` directly in your callbacks, not `Result<T, Error>`.
+
+```swift
+import Foundation
+import CometChatUIKitSwift
+import CometChatSDK
+
+final class CometChatManager {
+    
+    // MARK: - Singleton
+    static let shared = CometChatManager()
+    
+    // MARK: - State
+    private(set) var isInitialized = false
+    private(set) var currentUser: User?
+    
+    // MARK: - Callbacks
+    var onLoginStateChanged: ((User?) -> Void)?
+    
+    private init() {}
+    
+    // MARK: - Initialization
+    func initialize(
+        appID: String,
+        authKey: String,
+        region: String,
+        completion: @escaping (Bool, CometChatException?) -> Void
+    ) {
+        guard !isInitialized else {
+            completion(true, nil)
+            return
+        }
+        
+        let uiKitSettings = UIKitSettings()
+            .set(appID: appID)
+            .set(authKey: authKey)
+            .set(region: region)
+            .subscribePresenceForAllUsers()
+            .build()
+        
+        CometChatUIKit.init(uiKitSettings: uiKitSettings) { [weak self] result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success(let success):
+                    self?.isInitialized = success
+                    self?.currentUser = CometChatUIKit.getLoggedInUser()
+                    completion(success, nil)
+                case .failure(let error):
+                    completion(false, error as? CometChatException)
+                }
+            }
+        }
+    }
+    
+    // MARK: - Login with UID (Development)
+    func login(uid: String, completion: @escaping (User?, CometChatException?) -> Void) {
+        guard isInitialized else {
+            print("CometChat not initialized")
+            completion(nil, nil)
+            return
+        }
+        
+        if let user = currentUser {
+            completion(user, nil)
+            return
+        }
+        
+        CometChatUIKit.login(uid: uid) { [weak self] result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success(let user):
+                    self?.currentUser = user
+                    self?.onLoginStateChanged?(user)
+                    completion(user, nil)
+                case .onError(let error):
+                    completion(nil, error)
+                @unknown default:
+                    completion(nil, nil)
+                }
+            }
+        }
+    }
+    
+    // MARK: - Login with Auth Token (Production)
+    func loginWithToken(_ authToken: String, completion: @escaping (User?, CometChatException?) -> Void) {
+        guard isInitialized else {
+            print("CometChat not initialized")
+            completion(nil, nil)
+            return
+        }
+        
+        CometChatUIKit.login(authToken: authToken) { [weak self] result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success(let user):
+                    self?.currentUser = user
+                    self?.onLoginStateChanged?(user)
+                    completion(user, nil)
+                case .onError(let error):
+                    completion(nil, error)
+                @unknown default:
+                    completion(nil, nil)
+                }
+            }
+        }
+    }
+    
+    // MARK: - Logout
+    func logout(completion: @escaping (Bool, CometChatException?) -> Void) {
+        guard let user = currentUser else {
+            completion(true, nil)
+            return
+        }
+        
+        CometChatUIKit.logout(user: user) { [weak self] result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    self?.currentUser = nil
+                    self?.onLoginStateChanged?(nil)
+                    completion(true, nil)
+                case .onError(let error):
+                    completion(false, error)
+                @unknown default:
+                    completion(false, nil)
+                }
+            }
+        }
+    }
+}
+```
+
+### Usage Example
+
+```swift
+// Initialize
+CometChatManager.shared.initialize(
+    appID: "YOUR_APP_ID",
+    authKey: "YOUR_AUTH_KEY",
+    region: "us"
+) { success, error in
+    if success {
+        print("Initialized successfully")
+    } else if let error = error {
+        print("Init failed: \(error.errorDescription)")
+    }
+}
+
+// Login
+CometChatManager.shared.login(uid: "cometchat-uid-1") { user, error in
+    if let user = user {
+        print("Logged in as: \(user.name ?? "")")
+        // Show chat UI
+    } else if let error = error {
+        print("Login failed: \(error.errorDescription)")
+    }
+}
+
+// Logout
+CometChatManager.shared.logout { success, error in
+    if success {
+        print("Logged out")
+    } else if let error = error {
+        print("Logout failed: \(error.errorDescription)")
+    }
+}
+```
+
+---
+
+## 6. Theming
+
+### Global Theme Configuration
+
+CometChat iOS UI Kit uses `CometChatTheme` for styling. Configure it before showing any UI:
+
+```swift
+// Set primary color
+CometChatTheme.primaryColor = UIColor.systemBlue
+
+// Set background colors
+CometChatTheme.backgroundColor01 = UIColor.systemBackground
+CometChatTheme.backgroundColor02 = UIColor.secondarySystemBackground
+
+// Set text colors
+CometChatTheme.textColorPrimary = UIColor.label
+CometChatTheme.textColorSecondary = UIColor.secondaryLabel
+```
+
+### Component-Level Styling
+
+Each component has a static `style` property:
+
+```swift
+// Conversations list style
+CometChatConversations.style.backgroundColor = .systemBackground
+CometChatConversations.style.titleColor = .label
+
+// Message list style
+CometChatMessageList.style.backgroundColor = .systemBackground
+
+// Avatar style — cornerRadius is a CGFloat on a CometChatCornerStyle,
+// NOT a `.circle` enum case. Use a value larger than half the avatar
+// dimension for a circular look.
+CometChatAvatar.style.backgroundColor = .systemGray5
+CometChatAvatar.style.cornerRadius = CometChatCornerStyle(cornerRadius: 100)
+```
+
+### Dark Mode Support
+
+CometChat automatically supports dark mode when using system colors:
+
+```swift
+CometChatTheme.primaryColor = UIColor { traitCollection in
+    traitCollection.userInterfaceStyle == .dark 
+        ? UIColor.systemBlue 
+        : UIColor.blue
+}
+```
+
+---
+
+## 7. Localization
+
+CometChat iOS UI Kit supports 20+ languages out of the box. The language is automatically detected from the device settings.
+
+### Supported Languages
+
+Arabic, Chinese (Simplified), Chinese (Traditional), Dutch, English, French, German, Hindi, Hungarian, Japanese, Korean, Lithuanian, Malay, Portuguese, Russian, Spanish, Swedish, Turkish
+
+### Setting locale
+
+`CometChatLocalize` is a `Bundle` subclass that swaps the kit's `.lproj` lookup at runtime. The public API is locale-only:
+
+```swift
+CometChatLocalize.set(locale: .english)        // enum value
+CometChatLocalize.set(locale: "fr")            // raw string
+```
+
+There is no `CometChatLocalize.set(key:value:)` for ad-hoc key overrides — to customize specific strings, override them in your app's `Localizable.strings` file (the kit reads through the standard bundle lookup chain).
+
+---
+
+## 8. Anti-patterns
+
+These are specific things NOT to do. Each one causes real bugs.
+
+1. **Do NOT call `CometChatUIKit.init()` multiple times.** Init should happen once in AppDelegate or App init. Multiple init calls cause undefined behavior.
+
+2. **Do NOT show CometChat UI before init completes.** Components assume the SDK is initialized. Showing UI before init finishes causes crashes.
+
+3. **Do NOT hardcode Auth Key in production code.** The auth key is a secret. Use environment variables or xcconfig files. Use auth tokens in production.
+
+4. **Do NOT ignore the completion handler.** Init and login are async. Always handle the completion to know when it's safe to proceed.
+
+5. **Do NOT create multiple instances of CometChatManager.** Use the singleton pattern. Multiple managers cause state inconsistencies.
+
+6. **Do NOT call login while another login is in progress.** Check `currentUser` first. Concurrent login calls cause errors.
+
+7. **Do NOT forget to handle logout.** When your app's user logs out, call `CometChatManager.shared.logout()` to clear the CometChat session.
+
+8. **Do NOT ignore memory management.** CometChat view controllers should be properly deallocated. Avoid retain cycles with closures.
+
+9. **Do NOT block the main thread.** All CometChat callbacks are on the main thread. Don't do heavy work in callbacks.
+
+10. **Do NOT invent component names.** CometChat exports specific components with specific names. Check the `cometchat-ios-components` skill before writing any code.
+
+---
+
+## 9. SDK Types Reference
+
+Common types from `CometChatSDK`:
+
+```swift
+import CometChatSDK
+
+// User — represents a chat user
+let user: User
+
+// Group — represents a chat group
+let group: Group
+
+// Conversation — wraps User or Group
+let conversation: Conversation
+
+// BaseMessage — base class for all messages
+let message: BaseMessage
+
+// TextMessage — a text message
+let textMessage: TextMessage
+
+// MediaMessage — image, video, audio, file
+let mediaMessage: MediaMessage
+
+// CustomMessage — custom data message
+let customMessage: CustomMessage
+```
+
+### Getting entities
+
+```swift
+// Get a user by UID
+CometChat.getUser(UID: "user-uid") { user in
+    print("User: \(user?.name ?? "")")
+} onError: { error in
+    print("Error: \(error?.errorDescription ?? "")")
+}
+
+// Get a group by GUID
+CometChat.getGroup(GUID: "group-guid") { group in
+    print("Group: \(group?.name ?? "")")
+} onError: { error in
+    print("Error: \(error?.errorDescription ?? "")")
+}
+```
+
+---
+
+## 10. Package Dependencies
+
+Every CometChat iOS integration requires:
+
+```ruby
+# Podfile
+pod 'CometChatUIKitSwift', '~> 5.1'
+```
+
+This automatically includes:
+- `CometChatSDK` — Core SDK with types and methods
+- UI components and views
+- Localization resources
+- Asset bundles
+
+### Optional: Calling SDK
+
+For voice/video calls, add:
+
+```ruby
+pod 'CometChatCallsSDK', '~> 4.0'
+```
+
+The UI Kit automatically detects and enables calling features when the Calls SDK is present.