@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-core/references/setup-credentials.md

@@ -0,0 +1,197 @@
+# Setup & credentials (iOS UI Kit v5)
+
+> Verified against `CometChatUIKitSwift` 5.1.22 / `CometChatSDK` 4.1.7. Exact API always comes
+> from the docs `.md` twin via `docs-map.md` — never from memory and never from `.swiftinterface`.
+
+## 1. Detect before you add anything
+
+Read the project, don't ask what you can see:
+
+| Signal | Means |
+|---|---|
+| `Package.swift` / `*.xcodeproj` naming `CometChatUIKitSwift` | already integrated via SPM — REUSE, do not re-add |
+| `Podfile` naming `CometChatUIKitSwift` | integrated via **CocoaPods** — see *version_conflict* below |
+| `*.xcworkspace` present | CocoaPods project; open the workspace, never the `.xcodeproj` |
+| none of the above | greenfield add |
+
+## 2. Credentials — the full chain, including the two steps that make it work
+
+The chain is `Secrets.xcconfig` → build settings → `Info.plist` → `Bundle.main`. Drawing the chain
+is not enough: **an xcconfig that is not ATTACHED to the build configurations substitutes nothing**,
+and `Info.plist` only exposes a value if the key is DECLARED there. Miss either and
+`Bundle.main.infoDictionary` hands back the literal string `$(COMETCHAT_APP_ID)` — which is why the
+guard in step 4 exists, and why omitting these steps drops you straight into the failure it detects.
+
+### Step 0 — get the App ID / Region / Auth Key — OFFER to FETCH first, never default to "paste it yourself"
+Before writing any file, you need three values: **App ID · Region · Auth Key** (Auth Key is dev-only).
+**OFFER to fetch them from the CometChat Dashboard** — load the CLI on demand
+(`@3` pins the CLI major that matches the v5 skills):
+
+```bash
+npx @cometchat/skills-cli@3 auth login
+npx @cometchat/skills-cli@3 provision use --app-id <id> --json
+```
+
+Ask which EXISTING app; never auto-create. **Already have App ID / Region / Auth Key? Just paste them** —
+manual paste is the fallback, not the default. Mint **auth tokens server-side** for production; never
+ship the Auth Key (§4). The CLI is a dashboard/API client only (`auth`/`provision`/`config`/`features`) —
+it does NOT write env files or generate code; this skill does the wiring in Steps 1–5 below.
+
+### Step 1 — write the file (gitignored)
+
+`Config/Secrets.xcconfig`:
+
+```
+COMETCHAT_APP_ID = 123456abcdef
+COMETCHAT_REGION = us
+COMETCHAT_AUTH_KEY = <dev only — see §4>
+```
+
+Add `Config/Secrets.xcconfig` to `.gitignore` **before** you put a real value in it.
+
+> `//` starts a comment in an xcconfig, so any value containing it is silently truncated. Values
+> here are plain identifiers, but keep it in mind if you ever add a URL.
+
+### Step 2 — ATTACH it to the build configurations (the step everyone misses)
+
+*Xcode:* select the **project** (not the target) → **Info** → **Configurations** → expand **Debug**
+and **Release** → set the configuration file to `Secrets.xcconfig`.
+
+*xcodegen* (`project.yml`), at the top level:
+
+```yaml
+configFiles:
+  Debug: Config/Secrets.xcconfig
+  Release: Config/Secrets.xcconfig
+```
+
+Without this the keys are not build settings at all and nothing substitutes them.
+
+### Step 3 — DECLARE the keys in `Info.plist`
+
+Build settings are not visible to your code on their own. Each one you want at runtime must be
+declared as an `Info.plist` entry whose value is the `$(...)` reference.
+
+> **First check whether the project HAS an `Info.plist`.** Since Xcode 13 the default is
+> `GENERATE_INFOPLIST_FILE = YES` and there is no plist file in the project at all. You cannot add
+> a CUSTOM key to a generated plist through build settings — measured on Xcode 16:
+>
+> | build setting | reaches the built `Info.plist`? |
+> |---|---|
+> | `INFOPLIST_KEY_NSCameraUsageDescription` (an Apple-defined key) | **yes** |
+> | `INFOPLIST_KEY_COMETCHAT_APP_ID` (a custom key) | **no — silently dropped** |
+>
+> `INFOPLIST_KEY_*` only understands keys Apple defines. So on a generated-plist project, either
+> add a real `Info.plist` and point `INFOPLIST_FILE` at it, or add the keys through the target's
+> **Info** tab, which makes Xcode create one for you. The §3 usage descriptions below are Apple
+> keys, so those CAN stay as `INFOPLIST_KEY_*` build settings — it is only the `COMETCHAT_*`
+> credentials that need a real file.
+
+```xml
+<key>COMETCHAT_APP_ID</key>
+<string>$(COMETCHAT_APP_ID)</string>
+<key>COMETCHAT_REGION</key>
+<string>$(COMETCHAT_REGION)</string>
+<key>COMETCHAT_AUTH_KEY</key>
+<string>$(COMETCHAT_AUTH_KEY)</string>
+```
+
+### Step 4 — read it back, and fail loudly
+
+An unsubstituted value arrives as the literal `$(COMETCHAT_APP_ID)`, not as `nil` — a
+silent-wrong-value trap, so reject that form explicitly:
+
+```swift
+func credential(_ key: String) -> String? {
+    guard let v = Bundle.main.infoDictionary?[key] as? String,
+          !v.isEmpty, !v.hasPrefix("$(") else { return nil }   // reject the un-substituted form
+    return v
+}
+```
+
+### Step 5 — verify the substitution before blaming CometChat
+
+Build, then print `Bundle.main.infoDictionary?["COMETCHAT_APP_ID"]`. A real App ID means the chain
+works. The literal `$(COMETCHAT_APP_ID)` means step 2 or step 3 is missing — the credentials are
+fine and the wiring is not. An init/login failure here is NOT a CometChat problem.
+
+> For a shipping build, do not carry the Auth Key in the Release configuration at all — see §4.
+
+## 3. `Info.plist` usage descriptions
+
+The kit's media affordances call system pickers, and iOS terminates the app if the matching
+usage string is absent. Add the ones your chosen features actually need:
+
+| Key | Needed by |
+|---|---|
+| `NSCameraUsageDescription` | camera attachments, video calling |
+| `NSMicrophoneUsageDescription` | voice notes, voice/video calling |
+| `NSPhotoLibraryUsageDescription` | image/video attachments |
+
+Write a real sentence for each ("Take photos to send in chat") — App Review rejects placeholders.
+
+## 4. Auth Key vs auth token — the production rule
+
+- **Auth Key** authenticates as ANY user. It is a development convenience only. Shipping it in
+  an app binary hands every account to anyone who unzips the IPA.
+- **Production**: mint an auth token **server-side** and log in with it. The client never holds
+  the Auth Key.
+
+`login(uid:)` does NOT create users. On a fresh app the docs' pre-created test users are
+`cometchat-uid-1 … 5`; for any real app, ASK which UID to use rather than guessing.
+
+## 5. version_conflict
+
+CocoaPods distribution is winding down and its spec repo is going read-only, so **SPM is the
+only supported integration path**. A `Podfile` is a DETECTION signal, never an instruction.
+
+If the project already integrates via CocoaPods, STOP and surface the choice — do not silently
+add SPM alongside it. Two package managers resolving the same binary xcframework is the
+`version_conflict` case: state it, recommend migrating to SPM, and let the user decide.
+
+The kit is a prebuilt binary compiled against ONE SDK version, and SPM does not resolve that
+transitively — pin `CometChatSDK` to the exact version the kit requires, or you get link errors
+that look like missing symbols.
+
+## 6. `cometchat-settings.json` — telemetry attribution
+
+Separate from the xcconfig chain above, and required for CometChat to attribute the integration
+to the skills rather than to a hand-written one.
+
+`CometChatUIKit.initFromSettings` takes **no parameters**. That is not a limitation — it reads a
+JSON file from the app bundle. Create `cometchat-settings.json` and add it to the target's **Copy
+Bundle Resources**:
+
+```json
+{
+  "appId": "<your app id>",
+  "region": "<your region>",
+  "authKey": "<dev only — see §4>",
+  "presenceSubscription": { "type": "ALL_USERS" }
+}
+```
+
+Valid `presenceSubscription.type` values are `ALL_USERS`, `ROLES`, `FRIENDS`, `NONE` — the SDK
+rejects anything else by name. **Gitignore this file**: it carries the Auth Key, exactly like
+`Secrets.xcconfig`.
+
+### Call it BEFORE the classic init, not instead of it
+
+| init path | `integrationSource` | login / render |
+|---|---|---|
+| classic `CometChatUIKit(uiKitSettings:)` alone | *absent* — calls stamped **`"manual"`** | works |
+| `initFromSettings` alone | `"ai-agent"` | **fails — `Err_101`** |
+| `initFromSettings` **then** classic | `"ai-agent"` | works |
+
+Measured on 5.1.19 with the app container wiped between runs. On this version
+`initFromSettings` initialises the Chat SDK but leaves the UI Kit layer uninitialised, so using it
+alone breaks login — a kit defect, and the reason the recipe runs both.
+
+> Why this is worth the extra call: without it every app you build is attributed to
+> `"manual"`. That is not merely missing attribution, it is **wrong** attribution.
+
+> A note on verifying this API: `integrationSource` appears **nowhere** in the shipped
+> `.swiftinterface`, and an earlier version of this pack concluded from that fact that attribution
+> was impossible on iOS. That was wrong. The interface lists which SYMBOLS EXIST; it says nothing
+> about runtime behaviour or where a function's inputs come from. Both facts here came from the
+> shipped binaries and from measuring `UserDefaults`, not from the interface.

package/skills/cometchat-ios-core/references/swiftui.md

@@ -0,0 +1,91 @@
+# SwiftUI, and where `init → login` actually goes
+
+The kit is **UIKit-only**: every component is a `UIView`/`UIViewController`. It works in a SwiftUI
+app, but nothing about that is automatic, and the golden path in `SKILL.md` shows the code without
+saying where it lives. This file says where.
+
+> Verified on 5.1.22 by building and running a SwiftUI app from scratch: login succeeded and
+> `CometChatConversations` rendered with live data.
+
+## Where init and login go
+
+`init → login` must complete **before** any component renders, and it must run **once** for the
+process — not per view. SwiftUI views are values and their bodies re-evaluate freely, so a `.task`
+or `.onAppear` on a view is the wrong home for it.
+
+| lifecycle | put `init → login` in |
+|---|---|
+| **UIKit** (`AppDelegate` + `SceneDelegate`) | `application(_:didFinishLaunchingWithOptions:)` |
+| **SwiftUI** (`@main struct App`) | an `AppDelegate` attached with `@UIApplicationDelegateAdaptor` |
+
+A stock Xcode project today has **no `AppDelegate` and no `SceneDelegate`** — it is a SwiftUI
+`App`. Adding the adaptor is how you get a launch hook back.
+
+```swift
+final class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(_ app: UIApplication,
+                     didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+        CometChatUIKit.initFromSettings { _, _ in                    // attribution — see setup-credentials §6
+            CometChatUIKit.init(uiKitSettings: settings) { result in
+                if case .success = result {
+                    CometChatUIKit.login(uid: uid) { _ in
+                        DispatchQueue.main.async { AppState.shared.ready = true }
+                    }
+                }
+            }
+        }
+        return true
+    }
+}
+
+@main
+struct MyApp: App {
+    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
+    @ObservedObject private var state = AppState.shared
+    var body: some Scene {
+        WindowGroup {
+            if state.ready { ChatScreen() }        // render ONLY after login resolves
+            else { ProgressView() }
+        }
+    }
+}
+```
+
+`AppState` is any `ObservableObject` with a `ready` flag. Gating on it is not optional: rendering a
+component before login resolves is the silent-failure case the ordering rule exists to prevent.
+
+## Showing a UIKit component from SwiftUI
+
+Wrap it in `UIViewControllerRepresentable`. Wrap it in a `UINavigationController` too — the kit
+composes by navigation (list pushes the message pane), so without one the push has nowhere to go.
+
+```swift
+struct ConversationsView: UIViewControllerRepresentable {
+    func makeUIViewController(context: Context) -> UINavigationController {
+        let list = CometChatConversations()
+        // wire onItemClick here exactly as in the golden path
+        return UINavigationController(rootViewController: list)
+    }
+    func updateUIViewController(_ vc: UINavigationController, context: Context) {}
+}
+```
+
+**Qualify `CometChatSDK.User` / `CometChatSDK.Group` in any file that imports SwiftUI.** SwiftUI
+declares its own `Group`, so a bare `as? Group` is `'Group' is ambiguous for type lookup` — a
+guaranteed compile error in the wrapper file this page tells you to write. A live test hit exactly
+that. Host apps also very often define their own `User` model, so qualify both:
+
+```swift
+vc.user  = conversation.conversationWith as? CometChatSDK.User
+vc.group = conversation.conversationWith as? CometChatSDK.Group
+```
+
+The golden path in `SKILL.md` and the recipe in `layout.md` are already written this way; keep them
+qualified rather than "tidying" the module prefix away.
+
+`NavigationStack` does **not** substitute for this. The kit pushes with
+`UINavigationController.pushViewController`, which a SwiftUI `NavigationStack` does not provide.
+
+Rule 5 still applies inside that navigation controller — see `layout.md`. The coordinator goes on
+the `UINavigationController` you create in `makeUIViewController`, and something must hold it: the
+`delegate` is weak, and a coordinator created inline is deallocated immediately.

package/skills/cometchat-ios-core/references/troubleshooting.md

@@ -0,0 +1,100 @@
+# Troubleshooting — symptom → cause → fix
+
+Every entry here is a RUNTIME failure that compiled cleanly. That is the character of this kit:
+the compiler will not catch composition mistakes.
+
+## Blank screen, nothing renders
+
+**Cause:** `login()` ran before `init()` finished, or it failed and nothing surfaced the error.
+`login()` called early fails SILENTLY.
+
+**Fix:** nest them — never sequence with a timer. Render only after login succeeds:
+
+```swift
+CometChatUIKit.init(uiKitSettings: settings) { result in
+    switch result {
+    case .success:
+        CometChatUIKit.login(uid: uid) { loginResult in
+            switch loginResult {
+            case .success:            DispatchQueue.main.async { mountChat() }
+            case .onError(let e):     print("login failed:", e.errorDescription)
+            @unknown default:         break
+            }
+        }
+    case .failure(let e): print("init failed:", e.localizedDescription)
+    }
+}
+```
+
+Also check credentials actually resolved — an unsubstituted xcconfig value arrives as the
+literal `$(COMETCHAT_APP_ID)`, not nil (see `setup-credentials.md`).
+
+## The list renders but tapping a row does nothing
+
+**Cause:** `set(onItemClick:)` was never wired. The rows are real; the destination is not.
+
+**Fix:** push the message screen from the click handler, taking exactly one of user/group —
+see `layout.md`.
+
+## Tapping the composer makes the conversation disappear
+
+**Cause:** the composer is pinned to `view.keyboardLayoutGuide.topAnchor`. The kit's composer
+already adjusts for the keyboard, so this double-applies it — the message list collapses to height
+0 and the composer's own text field goes with it, leaving only the attachment/mic/send icons
+jammed under the header.
+
+**Fix:** pin the composer to `view.safeAreaLayoutGuide.bottomAnchor`, as the published recipe
+shows. The kit handles the keyboard from there.
+
+## Two navigation bars stacked on the message screen
+
+**Cause:** `CometChatMessageHeader` carries its own title and back control, and the
+`UINavigationController` bar is still visible above it.
+
+**Fix:** hide the nav bar on the message screen in `viewDidLoad`, restore it in
+`viewWillDisappear`. Do not hide it globally.
+
+## The message pane is a thin strip / everything is squashed at the top
+
+**Cause:** the list is not pinned both top AND bottom, so it sizes to its intrinsic content
+instead of filling the space between header and composer.
+
+**Fix:** add both constraints (Rule 4 in `layout.md`). Verify by opening a conversation, not by
+looking at the list screen — the collapse is only visible on the pushed screen.
+
+## An empty list that might be an error
+
+**Cause:** no `set(onError:)`, so a failed fetch looks exactly like an empty account.
+
+**Fix:** wire `set(onError:)` on every list component and surface the failure.
+
+## Replies render but never send
+
+**Cause:** the thread's parent was set through two different APIs — see `anti-patterns.md` §4.
+
+**Fix:** set the parent one way, per the docs for that component, then actually send a reply to
+confirm.
+
+## Link errors / missing symbols after adding the package
+
+**Cause:** `CometChatSDK` is not pinned to the exact version the binary kit was compiled
+against, or (on 5.1.19) `CometChatCallsSDK` is absent — the shipped interface hard-imports it,
+so even a chat-only app fails to compile without it.
+
+**Fix:** pin both exactly. See `anti-patterns.md` §5.
+
+## The group-members screen cannot be dismissed
+
+**Symptom:** you push `CometChatGroupMembers`, it renders correctly, and then there is no way back
+— the kit's Cancel control does nothing, a wired `set(onBack:)` never fires, and edge-swipe back is
+inert.
+
+**Status: reported and NOT reproduced by us.** An acceptance pass measured it (Cancel
+`action=didTapBackButton` inert across 3 taps, `set(onBack:)` instrumented and never called); an
+attempt to reproduce it in the review harness did not get far enough to confirm or refute. So there
+is no verified fix here, and none is invented: we do not know whether the fault is the recipe or
+the kit.
+
+**What to do:** treat "can the user leave this screen?" as a test you run, not a property you
+assume. If you hit it, give yourself a dismissal path you control — your own bar button, or
+presenting rather than pushing — and please report the exact flow so this can be pinned down.