@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-react-native-sdk/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: cometchat-react-native-sdk
+description: "The headless CometChat Chat SDK for React Native — a method → contract map for the fallback path, plus init/login ordering and listener lifecycle. Use when the UI Kit has no component for what you need, or when building a fully custom chat UI. Triggers: CometChat SDK React Native, headless chat RN, custom chat UI React Native, sendMessage React Native, CometChat listener leak, banned members RN, change my avatar, update my profile, update user details React Native, log the user out."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-sdk-react-native ^4.0.28"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native sdk headless methods listeners fallback"
+---
+
+> **Ground truth:** `@cometchat/chat-sdk-react-native@4` + catalog `rn-sdk-v4.json` (317 symbols).
+> Signatures in `references/method-map.md` are verbatim from the installed `.d.ts`, not from prose.
+> Docs: `/sdk/react-native/llms-react-native-v4.md` (scoped index).
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- **the UI Kit has no component** for what you need — the common case, see below
+- "build my own chat UI" · "just give me the data layer" · "sendMessage in React Native"
+- "duplicate messages" · "listener leak" · "how do I page through history"
+
+## Prerequisites & install
+The SDK ships **under** the UI Kit — if `core` is installed, so is this. A headless-only app
+installs it alone:
+
+```bash
+npm install @cometchat/chat-sdk-react-native@4 @react-native-async-storage/async-storage@^2.1.2
+```
+
+⚠️ Not `@cometchat/chat-sdk-javascript` — that is the web package.
+
+## The rule: UI Kit first, SDK as fallback
+
+For any feature, check whether the UI Kit has a component (`components` skill + the catalog).
+**If it does, use it.** Reach for the SDK only when it does not.
+
+On React Native that fallback path is **not rare**. Kit v5 removed the detail and management
+screens, so these have no component at all and are pure SDK work:
+
+| Need | Why there is no component | Map section |
+|---|---|---|
+| user / group details | `CometChatDetails` removed in v5 | Users & groups |
+| add members | `CometChatAddMembers` removed | Users & groups |
+| **view / unban banned members** | **no UI surface exists at all** | Users & groups |
+| transfer ownership | `CometChatTransferOwnership` removed | Users & groups |
+| call log detail | only the list ships | Calls |
+
+## The maps — page-wise first
+
+**`references/page-map.md`** — the primary index, **page-wise like the JavaScript SDK repo**:
+intent → the docs page → the methods that page demonstrates → the contract facts the RN page
+does not carry. 37 pages, derived from the live docs so it cannot drift. Start here.
+
+**`references/method-map.md`** — the per-method companion for when you already know the method
+and need its exact signature, return type and constraints. 80 methods, 127/127 accounted for.
+
+Both open with the same **fallback ladder**, and it matters: these cover most of the SDK, not
+all of it, so **"not listed" never means "does not exist."** Rung 2 is the catalog — that, not
+a map, is the existence authority.
+
+**Load `page-map.md` for any SDK question.** It answers, per method: signature, what it resolves to, what it
+rejects with, prerequisites, and what it will refuse to do. That last one matters most — it records
+**negative facts** a docs page cannot express by omission, e.g. *there is no `sendCardMessage()`*,
+which an agent would otherwise invent by symmetry with the three send methods that do exist.
+
+Each row is marked `D` (backed by the RN docs) or `T` (recovered from the `.d.ts` because the RN
+page is thin — **RN-G15**). Do not present a `T` row as documented; it is correct, and the docs gap
+is real.
+
+## Ordering — the invariant
+
+Init (`initFromSettings`) must resolve before `login()`. `login()` must resolve before you fetch or
+send. Anything else fails quietly rather than throwing.
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+// DEFAULT via skills: the ai-agent / telemetry-attributed init — persists integrationSource="ai-agent"
+// (RULES §Ordering), the SDK sibling of the UI Kit's initFromSettings. Web/JS settings-OBJECT form,
+// NOT the classic AppSettingsBuilder + init(APP_ID, settings). initFromSettings is @nodoc (ai-agent-only).
+await CometChat.initFromSettings({
+  appId: APP_ID,
+  region: REGION,
+  credentials: { authKey: AUTH_KEY },                        // dev only; prod logs in with an auth token
+  chatSDK: { presenceSubscription: { type: "ALL_USERS" } },  // = the old .subscribePresenceForAllUsers()
+});
+await CometChat.login(UID, AUTH_KEY);   // dev only; production passes an auth token
+
+// FALLBACK only (non-skills / doc-following context) — the publicly-documented classic path:
+//   const settings = new CometChat.AppSettingsBuilder()
+//     .setRegion(REGION).subscribePresenceForAllUsers().autoEstablishSocketConnection(true).build();
+//   await CometChat.init(APP_ID, settings);
+```
+
+⚠️ `login` is **variadic and untyped** in the `.d.ts` (`login(...args: any)`), so TypeScript will
+**not** catch a wrong call. The two real shapes are `login(uid, authKey)` and `login(authToken)`.
+
+## Listener lifecycle — the defect this skill exists to prevent
+
+```tsx
+useEffect(() => {
+  const id = "chat-screen";
+  CometChat.addMessageListener(id, new CometChat.MessageListener({
+    onTextMessageReceived: (m) => setMessages((prev) => [...prev, m]),
+  }));
+  return () => CometChat.removeMessageListener(id);   // NOT optional
+}, []);
+```
+
+`addMessageListener` returns **void**, not a subscription — the string id is your only handle. The
+SDK holds the listener, not React, so it survives navigation and unmount. Omitting the cleanup is
+the top cause of duplicate messages, and it worsens the longer the app runs.
+
+## Fetching is always a builder
+Lists are paginated: `new CometChat.XRequestBuilder().setLimit(n).build()` then `.fetchNext()`.
+An empty array means the end — it does not throw. There is no bare `getMessages()`.
+
+## Common pitfalls
+1. **Dropping the listener cleanup** — duplicate messages that grow over time.
+2. **Calling a bare `sendMessage()`** — everything is namespaced under `CometChat`.
+3. **Inventing `sendCardMessage()`** — card messages are receive-only.
+4. **`await`ing `startTyping`** — it returns void.
+5. **Treating `getLoggedinUser()` returning `null` as an error** — it is the normal no-session answer. (Note the lowercase `in`.)
+6. **Shipping ban without unban** — `CometChatGroupMembers` shows active members only; wire `BannedMembersRequestBuilder` + `unbanGroupMember` too.
+7. **Registering a push token before `login` resolves** — it belongs to no user.
+
+## Verify it works
+- Every symbol appears in `catalogs/rn-sdk-v4.json`.
+- `npm run verify:fences:rn-v5` is green.
+- Every `add*Listener` has a matching `remove*Listener` on the teardown path.
+- Pagination, error handling and the ban round trip are wired — not just the happy path.

package/skills/cometchat-react-native-sdk/references/method-map.md

@@ -0,0 +1,239 @@
+# method-map — CometChat React Native Chat SDK v4
+
+The **fallback lookup**: which method, what it returns, what it throws, what it refuses to do.
+
+Field names follow the **JavaScript SDK's** contract schema (derived from all 20 of its
+documented pages), so the two read identically:
+`Package` · `Import` · `Key methods` · `Key classes` · `Primary output` · `Prerequisites` ·
+`Constraints` · `Listeners registered` · `Request builder` · `Related`.
+
+Signatures are **verbatim from the installed `.d.ts`** of `@cometchat/chat-sdk-react-native@4.0.28`.
+Every symbol is in `catalogs/rn-sdk-v4.json` (317 symbols).
+
+---
+
+## ⚠️ IF IT IS NOT IN THIS MAP — the fallback ladder
+
+This map covers **~60 of the SDK's 127 methods**. That is deliberate: a dump of all 127 would
+include internals nobody should call, and a map nobody reads is worse than no map.
+
+**So "not listed here" does NOT mean "does not exist."** Never conclude absence from this file.
+Walk the ladder instead — each rung is cheaper than the one below it:
+
+| # | Rung | Answers | Cost |
+|---|---|---|---|
+| 1 | **this map** | full contract | free |
+| 2 | **`catalogs/rn-sdk-v4.json`** | *does it exist at all?* **Not in the catalog ⇒ it does not exist — do not emit it.** | free |
+| 3 | **scoped SDK index** — `{DOCS_BASE}/sdk/react-native/llms-react-native-v4.md` | which page covers it | ~3k tok |
+| 4 | **that page + `.md`** | its Quick Reference accordion, then prose | 1 page |
+| 5 | **the installed `.d.ts`** | the signature, when the page is thin | last resort |
+
+**Rung 5 carries an obligation.** If you had to read the `.d.ts` because the docs did not answer,
+that is a **DOCS GAP** — flag it for the developer (page · what is missing · why it mattered).
+Never silently source-fill: a gap that is filled quietly is a gap that is never fixed, and the
+next agent re-derives it from scratch.
+
+Two things this map will never cover, by design:
+- **calls** — a different package (`@cometchat/calls-sdk-react-native`); see the `calls` skill
+- **internals** — `getApiKey` · `getAppId` · `connect` · `disconnect` · `isInitialized` ·
+  `getConnectionStatus` · `setSource` · `setDemoMetaInfo`. They exist; a chat integration has
+  no reason to call them.
+
+> Everything hangs off the namespace: `import { CometChat } from "@cometchat/chat-sdk-react-native"`.
+> A bare `sendMessage()` does not exist. The RN docs frequently print the bare form.
+
+Row source: **`D`** = backed by the RN docs · **`T`** = recovered from the `.d.ts` because the RN
+page is thin (**RN-G15**). A `T` row is correct but **not documented** — say so if you rely on it.
+
+---
+
+## Lifecycle
+
+| Field | Value |
+|---|---|
+| Package | `@cometchat/chat-sdk-react-native` |
+| Import | `import { CometChat } from "@cometchat/chat-sdk-react-native";` |
+| Key classes | `AppSettingsBuilder` · `AppSettings` · `User` · `CometChatException` |
+| Prerequisites | none — this is the entry point |
+| Constraints | `init` must **resolve** before `login`; `login` must resolve before any fetch or send. Out of order fails **quietly**, not loudly. |
+
+| Method | Signature | Returns | Notes | Src |
+|---|---|---|---|---|
+| `init` | `init(appId: any, appSettings: AppSettings): Promise<boolean>` | `true` | rejects `CometChatException`; always `await` and log | D |
+| `initFromSettings` | `initFromSettings(settings): Promise<boolean>` | `true` | settings-object form; also sets telemetry attribution | T |
+| `login` | `login(...args: any): Promise<User>` | `User` | **VARIADIC AND UNTYPED** — TS catches nothing. Real shapes: `login(uid, authKey)` dev, `login(authToken)` prod | T |
+| `logout` | `logout(): Promise<Object>` | — | unregister the push token **first** | D |
+| `getLoggedinUser` | `getLoggedinUser(): Promise<User \| null>` | `User` or **`null`** | `null` = no session, **not an error**. Lowercase **`in`** | T |
+
+## Messaging — send
+
+| Field | Value |
+|---|---|
+| Key classes | `TextMessage` · `MediaMessage` · `CustomMessage` · `InteractiveMessage` |
+| Primary output | `Promise<BaseMessage>` — resolves the **sent** message; rejects `CometChatException` |
+| Receiver targeting | `RECEIVER_TYPE.USER` → a **UID** · `RECEIVER_TYPE.GROUP` → a **GUID** |
+| Constraints | **There is no `sendCardMessage()`.** Card/interactive messages are **receive-only** from the client — verified absent from the catalog. Do not invent it by symmetry with the three that exist. |
+| Receive counterpart | `addMessageListener` — see Listeners |
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `sendMessage` | `sendMessage(message: TextMessage \| MediaMessage \| CustomMessage \| InteractiveMessage \| any): Promise<…>` | the one you want in almost every case | D |
+| `sendMediaMessage` | `sendMediaMessage(message: Object): Promise<…>` | attachment count is server-capped; over it **rejects**, not truncates | T |
+| `sendCustomMessage` | `sendCustomMessage(message): Promise<…>` | app-defined JSON payloads | D |
+| `sendInteractiveMessage` | `sendInteractiveMessage(message): Promise<…>` | forms/schedulers | T |
+| `sendTransientMessage` | `sendTransientMessage(message): void` | ephemeral (live reactions); **not persisted, returns void** | T |
+| `sendDirectMessage` | `sendDirectMessage(message: Object): Promise<…>` | 1:1 variant — **coexists with `sendMessage`, neither marked deprecated.** Prefer `sendMessage`; the docs use it | T |
+| `sendGroupMessage` | `sendGroupMessage(message: any): Promise<…>` | group variant, same caveat | T |
+
+## Messaging — modify & moderate
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `editMessage` | `editMessage(message): Promise<BaseMessage>` | resolves the edited message | T |
+| `deleteMessage` | `deleteMessage(messageId): Promise<BaseMessage>` | soft delete — resolves a **tombstone**, the message does not vanish | T |
+| `getMessageDetails` | `getMessageDetails(messageId): Promise<BaseMessage>` | single message by id | T |
+| `flagMessage` | `flagMessage(messageId, reason): Promise<…>` | moderation report | T |
+| `getFlagReasons` | `getFlagReasons(): Promise<…>` | fetch the allowed reasons — **do not hardcode them** | T |
+| `addReaction` | `addReaction(messageId, reaction: string): Promise<BaseMessage>` | reactions are **core** in v5, no extension to enable | T |
+| `removeReaction` | `removeReaction(messageId, reaction: string): Promise<BaseMessage>` | | T |
+
+## Receipts, typing & unread
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `markAsRead` | `markAsRead(...args: any): any` | **untyped, returns `any`** — treat as fire-and-forget | T |
+| `markAsDelivered` | `markAsDelivered(...args): any` | usually automatic; call only for custom flows | T |
+| `markAsUnread` | `markAsUnread(message): Promise<…>` | | T |
+| `markConversationAsRead` | `markConversationAsRead(conversation): Promise<…>` | whole conversation at once | T |
+| `getMessageReceipts` | `getMessageReceipts(messageId): Promise<Array<MessageReceipt>>` | per-recipient delivery/read state | T |
+| `markConversationAsDelivered` | `markConversationAsDelivered(conversation): Promise<…>` | conversation-level pair of `markConversationAsRead` | T |
+| `markMessageAsUnread` | `markMessageAsUnread(message): Promise<…>` | **coexists with `markAsUnread`**, neither deprecated — prefer `markAsUnread` | T |
+| `getLastDeliveredMessageId` | `getLastDeliveredMessageId(...): any` | resume point for a receipt sync | T |
+| `markAsInteracted` | `markAsInteracted(messageId, interactionElementId): Promise<…>` | required for **interactive** messages, or engagement never registers | T |
+| `startTyping` | `startTyping(typingNotification): void` | **void — do not `await`** | T |
+| `endTyping` | `endTyping(typingNotification): void` | must be called explicitly; no client-side auto-expiry | T |
+| `getUnreadMessageCount` | `getUnreadMessageCount(...): Promise<Object>` | **Family:** `…ForUser` · `…ForGroup` · `…ForAllUsers` · `…ForAllGroups` are scoped variants with the same shape — pick by scope; not listed individually | T |
+
+## Users
+
+| Field | Value |
+|---|---|
+| Key classes | `User` · `UsersRequestBuilder` |
+| Request builder | `new CometChat.UsersRequestBuilder().setLimit(n).build()` then `.fetchNext()` |
+| Constraints | **`createUser` needs the Auth Key** → it is a **backend** call. A client that can create users can create *any* user. |
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `getUser` | `getUser(uid: any): Promise<User>` | | D |
+| `updateUser` | `updateUser(user, authKey): Promise<User>` | Auth Key ⇒ backend only | T |
+| `updateCurrentUserDetails` | `updateCurrentUserDetails(user): Promise<User>` | the **client-safe** way for a user to edit themselves | T |
+| `blockUsers` | `blockUsers(uids: Array<string>): Promise<Object>` | takes an **array**, not one uid | T |
+| `unblockUsers` | `unblockUsers(uids: Array<string>): Promise<Object>` | | T |
+| `getOnlineUserCount` | `getOnlineUserCount(): Promise<number>` | cheaper than paging users just to count presence | T |
+| `getOnlineGroupMemberCount` | `getOnlineGroupMemberCount(guids): Promise<Object>` | per-group online counts | T |
+
+## Groups
+
+| Field | Value |
+|---|---|
+| Key classes | `Group` · `GroupMember` · `GroupMembersRequestBuilder` · `BannedMembersRequestBuilder` |
+| Request builder | `GroupMembersRequestBuilder` lists **active** members · `BannedMembersRequestBuilder` lists **banned** ones |
+| Constraints | ban/unban/kick/transfer are **admin or owner scope only**. Kit v5 ships **no component** for add-members, banned-members, details or transfer — this is the whole implementation surface. |
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `createGroup` | `createGroup(group): Promise<Group>` | | T |
+| `createGroupWithMembers` | `createGroupWithMembers(group, members, banned): Promise<Object>` | create + seed in one call — saves an `addMembersToGroup` round trip | T |
+| `getGroup` | `getGroup(guid: string \| Object): Promise<Group>` | | D |
+| `updateGroup` | `updateGroup(group: any): Promise<Group>` | | T |
+| `deleteGroup` | `deleteGroup(guid): Promise<boolean>` | | T |
+| `joinGroup` | `joinGroup(guid, type, password?): Promise<Group>` | password only for password-protected groups | T |
+| `leaveGroup` | `leaveGroup(guid): Promise<boolean>` | | T |
+| `addMembersToGroup` | `addMembersToGroup(guid: string, groupMembers: Array<GroupMember>, bannedMembersList: Array<string>): Promise<Object>` | **THREE args** — the third is easy to forget | T |
+| `kickGroupMember` | `kickGroupMember(guid, uid): Promise<boolean>` | reversible — the user may rejoin | T |
+| `banGroupMember` | `banGroupMember(guid, uid): Promise<boolean>` | **one half of a round trip** ↓ | T |
+| `unbanGroupMember` | `unbanGroupMember(guid, uid): Promise<boolean>` | the other half | T |
+| `updateGroupMemberScope` | `updateGroupMemberScope(guid, uid, scope): Promise<string>` | promote/demote | T |
+| `transferGroupOwnership` | `transferGroupOwnership(guid, uid): Promise<string>` | resolves a **string**, not a `Group` | T |
+
+> ⚠️ **The ban round trip.** `CometChatGroupMembers` shows **active** members only and v5 ships no
+> banned-members UI. An app that offers ban and nothing else leaves the admin unable to see or
+> reverse it. Always ship `BannedMembersRequestBuilder` + `unbanGroupMember` alongside `banGroupMember`.
+
+## Conversations
+
+| Field | Value |
+|---|---|
+| Request builder | `new CometChat.ConversationsRequestBuilder().setLimit(n).build()` → `.fetchNext()`; an **empty array means the end**, it does not throw |
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `getConversation` | `getConversation(conversationWith, type): Promise<Conversation>` | | T |
+| `deleteConversation` | `deleteConversation(conversationWith, type): Promise<string>` | | T |
+| `muteConversations` | `muteConversations(...): Promise<…>` | | T |
+| `unmuteConversations` | `unmuteConversations(...): Promise<…>` | | T |
+| `tagConversation` | `tagConversation(...): Promise<Conversation>` | custom tags (pin, archive) | T |
+| `getMutedConversations` | `getMutedConversations(): Promise<Array<Conversation>>` | the read side of mute/unmute — without it the mute state is write-only | T |
+
+## Listeners — every `add` has a `remove`
+
+| Field | Value |
+|---|---|
+| Primary output | **`void`** — not a subscription. The string `name` is your only handle. |
+| Constraints | The **SDK** holds the listener, not React — it survives unmount and navigation. Omitting the removal is the top cause of duplicate messages, and it worsens the longer the app runs. |
+
+| Register | Remove | Covers | Src |
+|---|---|---|---|
+| `addMessageListener(name, l)` | `removeMessageListener(name)` | messages, typing, receipts, reactions | D |
+| `addUserListener(name, l)` | `removeUserListener(name)` | presence (online/offline) | T |
+| `addGroupListener(name, l)` | `removeGroupListener(name)` | joins, leaves, kicks, bans, scope changes | T |
+| `addCallListener(name, l)` | `removeCallListener(name)` | call lifecycle — see the `calls` skill | T |
+| `addLoginListener(name, l)` | `removeLoginListener(name)` | session/token expiry | T |
+| `addConnectionListener(name, l)` | `removeConnectionListener(name)` | socket connect/disconnect | T |
+| `addAIAssistantListener(name, l)` | `removeAIAssistantListener(name)` | AI assistant streaming | T |
+| `addNotificationFeedListener(name, l)` | `removeNotificationFeedListener(name)` | in-app notification feed | T |
+
+## Push
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `CometChatNotifications.registerPushToken` | `registerPushToken(pushToken: string, platform: PushPlatforms, providerId?: string): Promise<string>` | **the one the docs use.** Register **after** `login` resolves. Platform constant differs per OS — fetch it, do not guess | D |
+| `CometChatNotifications.unregisterPushToken` | `unregisterPushToken(): Promise<string>` | on logout — skip it and the next user of the device gets the previous user's pushes | D |
+| `markPushNotificationDelivered` | `markPushNotificationDelivered(...): Promise<…>` | delivery analytics; optional | T |
+| `markPushNotificationClicked` | `markPushNotificationClicked(...): Promise<…>` | click-through analytics; optional | T |
+| `registerTokenForPushNotification` | `registerTokenForPushNotification(token: string, settings?: {}): Promise<string>` | **an older, different signature that still exists and is NOT marked deprecated.** Two live ways to do one thing — prefer `registerPushToken`; flagged so the wrong one is not picked by accident | T |
+
+## AI & feature gates
+
+| Method | Signature | Notes | Src |
+|---|---|---|---|
+| `getConversationSummary` | `getConversationSummary(receiverId, receiverType): Promise<string>` | dashboard-gated | T |
+| `getConversationStarter` | `getConversationStarter(receiverId, receiverType): Promise<Array<string>>` | dashboard-gated | T |
+| `getSmartReplies` | `getSmartReplies(receiverId, receiverType): Promise<Object>` | dashboard-gated | T |
+| `askBot` | `askBot(...): Promise<Object>` | AI bots | T |
+| `isFeatureEnabled` | `isFeatureEnabled(feature: string): boolean` | check before offering a gated feature | T |
+| `isAIFeatureEnabled` | `isAIFeatureEnabled(feature: string): boolean` | AI equivalent | T |
+| `isExtensionEnabled` | `isExtensionEnabled(extensionId: string): boolean` | check before wiring a dashboard extension | T |
+| `getExtensionDetails` | `getExtensionDetails(extensionId): Promise<Object>` | config for an enabled extension | T |
+
+---
+
+## Deliberately excluded — and why
+
+Named here so "absent" reads as *out of scope*, never as *forgotten*:
+
+| Excluded | Count | Why |
+|---|---|---|
+| calls (`initiateCall`, `acceptCall`, `endCall`, …) | 11 | different package; the `calls` skill owns them |
+| internals (`getApiKey`, `connect`, `isInitialized`, …) | 11 | a chat integration has no reason to call them |
+| unread-count scoped variants | 4 | same shape as `getUnreadMessageCount`; documented as a family |
+| preferences / push-preferences / timezone | 8 | niche; reach them via the ladder |
+| notification-feed item methods | 5 | narrow feature; `addNotificationFeedListener` is the entry point |
+| `createUploadFileRequest` | 1 | internal upload plumbing — **not even a public export** (absent from `catalogs/rn-sdk-v4.json`); `sendMediaMessage` is the public path |
+| `reportFeedEngagement` | 1 | notification-feed analytics; same cluster as above |
+
+**Accounting: 127 of 127.** Every method in the SDK is either mapped above or excluded here with
+a reason. Nothing is silently absent — that is the property that makes rung 2 of the ladder
+trustworthy.
+
+Anything above is still **in the catalog** — rung 2 confirms it exists, rung 3 finds its page.

package/skills/cometchat-react-native-sdk/references/page-map.md

@@ -0,0 +1,96 @@
+# page-map — CometChat React Native Chat SDK v4: intent → page → contract
+
+**Page-wise, exactly like the JavaScript SDK repo.** One row per docs page: the intent it
+answers, the page to fetch, the methods it demonstrates, and the contract facts the RN page
+does **not** carry.
+
+Fetch a page as `{SDK_DOCS_BASE}/sdk/react-native/<page>` **+ `.md`**. `QR` marks pages that
+already carry an "AI Integration Quick Reference" accordion — read it first when present.
+
+Rows and method lists are **derived from the live RN docs pages**, not hand-typed, so they
+cannot drift from what the pages actually demonstrate. Every method named is in
+`catalogs/rn-sdk-v4.json`.
+
+---
+
+## ⚠️ IF THE PAGE OR METHOD IS NOT HERE — the fallback ladder
+
+This maps **37 pages**. It is not the whole SDK, and **"not listed" NEVER means "does not
+exist."** Walk the ladder, cheapest rung first:
+
+| # | Rung | Answers |
+|---|---|---|
+| 1 | **this page-map** | which page · which methods · the traps |
+| 2 | **`catalogs/rn-sdk-v4.json`** (317 symbols) | *does it exist at all?* **Not in the catalog ⇒ do not emit it.** |
+| 3 | **scoped index** `/sdk/react-native/llms-react-native-v4.md` | which page covers it (~3k tok) |
+| 4 | **that page + `.md`** | its Quick Reference, then prose |
+| 5 | **the installed `.d.ts`** | the signature — last resort, **and flag a DOCS GAP** |
+
+Rung 5 carries an obligation: if the docs did not answer and you read the `.d.ts`, that **is** a
+docs gap — flag it (page · what is missing · why it mattered). Silently source-filling
+guarantees the next agent re-derives it.
+
+**Not covered here by design:** calls (a different package — see the `calls` skill) and SDK
+internals (`getApiKey`, `getAppId`, `connect`, `disconnect`, `isInitialized`, `setSource`).
+
+> Everything is namespaced: `import { CometChat } from "@cometchat/chat-sdk-react-native"`.
+> A bare `sendMessage()` does not exist — the RN docs often print the bare form.
+
+---
+
+| Intent | Page (`+ .md`) | Methods it demonstrates | QR | Contract facts the page does NOT carry |
+|---|---|---|---|---|
+| AI agents | [`ai-agents`](/sdk/react-native/ai-agents) | `addAIAssistantListener` · `addMessageListener` · `init` · `login` · `removeAIAssistantListener` · `removeMessageListener` | ✓ |  |
+| add members | [`group-add-members`](/sdk/react-native/group-add-members) | `addGroupListener` · `addMembersToGroup` · `removeGroupListener` | ✓ | `addMembersToGroup(guid, groupMembers, bannedMembersList)` takes **three** args — the third is easy to omit. |
+| all listeners | [`real-time-listeners`](/sdk/react-native/real-time-listeners) | `addCallListener` · `addGroupListener` · `addMessageListener` · `addUserListener` · `removeCallListener` · `removeGroupListener` … | ✓ | **Every `add*Listener(id, …)` needs `remove*Listener(id)` on teardown.** The SDK holds the listener, not React, so it survives unmount — the top cause of duplicate messages. |
+| attachments | [`upload-files`](/sdk/react-native/upload-files) | `logout` · `sendMediaMessage` | — |  |
+| block · unblock | [`block-users`](/sdk/react-native/block-users) | `blockUsers` · `unblockUsers` | ✓ | `blockUsers` / `unblockUsers` take an **array** of uids, not a single uid. |
+| campaigns · notification feed | [`campaigns`](/sdk/react-native/campaigns) | `addMessageListener` · `addNotificationFeedListener` · `getNotificationFeedItem` · `getNotificationFeedUnreadCount` · `markFeedItemAsDelivered` · `markFeedItemAsRead` … | — |  |
+| connection state | [`connection-status`](/sdk/react-native/connection-status) | `addConnectionListener` · `getConnectionStatus` · `init` · `removeConnectionListener` | ✓ | `connect`/`disconnect` are internals — only for manual socket control, which most apps should not do. |
+| conversation list | [`retrieve-conversations`](/sdk/react-native/retrieve-conversations) | `getConversation` · `tagConversation` | ✓ | Paginated: `new CometChat.ConversationsRequestBuilder().setLimit(n).build()` → `.fetchNext()`. An **empty array means the end** — it does not throw. |
+| create a group | [`create-group`](/sdk/react-native/create-group) | `createGroup` · `createGroupWithMembers` | ✓ |  |
+| create/update a user | [`user-management`](/sdk/react-native/user-management) | `createUser` · `updateCurrentUserDetails` · `updateUser` | ✓ | `updateUser` needs the Auth Key ⇒ backend. `updateCurrentUserDetails` is the **client-safe** way for a user to edit themselves. |
+| delete a conversation | [`delete-conversation`](/sdk/react-native/delete-conversation) | `deleteConversation` | ✓ |  |
+| delete a group | [`delete-group`](/sdk/react-native/delete-group) | `deleteGroup` | ✓ |  |
+| delete a message | [`delete-message`](/sdk/react-native/delete-message) | `addMessageListener` · `deleteMessage` | ✓ | Soft delete — resolves a **tombstone**; the message does not vanish. |
+| edit a message | [`edit-message`](/sdk/react-native/edit-message) | `addMessageListener` · `editMessage` · `removeMessageListener` | ✓ |  |
+| ephemeral messages | [`transient-messages`](/sdk/react-native/transient-messages) | `addMessageListener` · `sendTransientMessage` | ✓ | `sendTransientMessage` returns **void** and is **not persisted**. |
+| group list | [`retrieve-groups`](/sdk/react-native/retrieve-groups) | `getGroup` · `getOnlineGroupMemberCount` | ✓ | Paginated via `GroupsRequestBuilder`. |
+| install · init | [`setup-sdk`](/sdk/react-native/setup-sdk) | `init` · `login` | ✓ | `init` must **resolve** before `login`. Build settings with `AppSettingsBuilder`. Out of order fails **quietly**. |
+| join a group | [`join-group`](/sdk/react-native/join-group) | `addGroupListener` · `joinGroup` · `removeGroupListener` | ✓ |  |
+| kick · ban · unban | [`group-kick-ban-members`](/sdk/react-native/group-kick-ban-members) | `addGroupListener` · `banGroupMember` · `kickGroupMember` · `removeGroupListener` · `unbanGroupMember` | ✓ | ⚠️ **The ban round trip.** `CometChatGroupMembers` lists **active** members only and kit v5 ships no banned-members UI. Pair `banGroupMember` with `BannedMembersRequestBuilder` + `unbanGroupMember`, or the admin cannot see or reverse a ban (RN twin of React AUDIT-082). |
+| leave a group | [`leave-group`](/sdk/react-native/leave-group) | `addGroupListener` · `leaveGroup` · `removeGroupListener` | ✓ |  |
+| login · logout · session | [`authentication-overview`](/sdk/react-native/authentication-overview) | `createUser` · `getLoggedinUser` · `login` · `logout` | ✓ | `login(...args: any)` is **variadic and untyped** — TS catches nothing. Shapes: `login(uid, authKey)` dev, `login(authToken)` prod. `getLoggedinUser()` returns `User \| null`; `null` is the normal no-session answer. Note the lowercase **`in`**. `createUser` needs the Auth Key ⇒ **backend only**. |
+| manual socket control | [`managing-web-sockets-connections-manually`](/sdk/react-native/managing-web-sockets-connections-manually) | `connect` · `disconnect` · `getLoggedinUser` · `init` · `login` · `ping` | ✓ |  |
+| mentions | [`mentions`](/sdk/react-native/mentions) | `sendMessage` | ✓ |  |
+| moderation | [`ai-moderation`](/sdk/react-native/ai-moderation) | `addMessageListener` · `removeMessageListener` · `sendMessage` | ✓ |  |
+| online/offline presence | [`user-presence`](/sdk/react-native/user-presence) | `addUserListener` · `init` · `removeUserListener` | ✓ | Requires `subscribePresenceForAllUsers()` in `AppSettingsBuilder` at init. |
+| orientation | [`overview`](/sdk/react-native/overview) | `getLoggedinUser` · `init` · `login` | ✓ |  |
+| promote/demote a member | [`group-change-member-scope`](/sdk/react-native/group-change-member-scope) | `addGroupListener` · `removeGroupListener` · `updateGroupMemberScope` | ✓ |  |
+| reactions | [`reactions`](/sdk/react-native/reactions) | `addMessageListener` · `addReaction` · `removeMessageListener` · `removeReaction` | ✓ | Reactions are **core** in kit v5 — there is no extension to enable. Offering the legacy dashboard extension is a defect (React AUDIT-077). |
+| receipts | [`delivery-read-receipts`](/sdk/react-native/delivery-read-receipts) | `addMessageListener` · `getMessageReceipts` · `markAsDelivered` · `markAsRead` · `markConversationAsDelivered` · `markConversationAsRead` … | ✓ | `markAsRead(...args: any): any` is **untyped** — treat as fire-and-forget. |
+| receive messages · unread counts | [`receive-messages`](/sdk/react-native/receive-messages) | `addMessageListener` · `getLastDeliveredMessageId` · `getMessageDetails` · `getUnreadMessageCount` · `getUnreadMessageCountForAllGroups` · `getUnreadMessageCountForAllUsers` … | ✓ | `addMessageListener` returns **void**, not a subscription — the string id is your only handle. `getUnreadMessageCount` has scoped variants (`…ForUser` / `ForGroup` / `ForAllUsers` / `ForAllGroups`) with the same shape. |
+| report a message | [`flag-message`](/sdk/react-native/flag-message) | `flagMessage` · `getFlagReasons` | ✓ | Fetch the allowed reasons with `getFlagReasons()` — **do not hardcode them**. |
+| send a message | [`send-message`](/sdk/react-native/send-message) | `sendCustomMessage` · `sendMediaMessage` · `sendMessage` | ✓ | **There is no `sendCardMessage()`** — card/interactive messages are receive-only from the client (verified absent from the catalog). Do not invent it by symmetry. `receiverType`: `RECEIVER_TYPE.USER` → a **UID**, `GROUP` → a **GUID**. |
+| threads | [`threaded-messages`](/sdk/react-native/threaded-messages) | `addMessageListener` · `removeMessageListener` · `sendMessage` | ✓ |  |
+| transfer ownership | [`transfer-group-ownership`](/sdk/react-native/transfer-group-ownership) | `transferGroupOwnership` | ✓ | resolves a **string**, not a `Group`. |
+| typing | [`typing-indicators`](/sdk/react-native/typing-indicators) | `addMessageListener` · `endTyping` · `removeMessageListener` · `startTyping` | ✓ | `startTyping` / `endTyping` return **void — do not `await`**. `endTyping` must be called explicitly; there is no client-side auto-expiry. |
+| update a group | [`update-group`](/sdk/react-native/update-group) | `updateGroup` | ✓ |  |
+| user list · presence count | [`retrieve-users`](/sdk/react-native/retrieve-users) | `getLoggedinUser` · `getOnlineUserCount` · `getUser` | ✓ | Paginated via `UsersRequestBuilder`. `getOnlineUserCount()` is cheaper than paging just to count presence. |
+
+---
+
+## RN-G15 — why the "contract facts" column exists at all
+
+The **JavaScript** SDK carries a full contract table on every page — `Package` · `Import` ·
+`Key methods` · `Primary output` · `Prerequisites` · `Constraints` · `Key classes` ·
+`Listeners registered` · `Request builder` · `Related` · `Full reference` — median **10 rows**
+across its 20 documented pages.
+
+The React Native pages carry a name list or a bare code snippet, and are thinner on **13 of 15**
+shared pages. So return types, error types and constraints are largely absent.
+
+Everything in the last column was recovered from the installed `.d.ts` or from the kit source.
+It is correct, and it is **not documented** — say so when you rely on it, rather than presenting
+it as if the page said it. When RN's pages gain the JS-style table, this column shrinks to a
+pointer.

package/skills/cometchat-react-native-testing/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cometchat-react-native-testing
+description: "Test a CometChat React Native integration — mock the SDK for Jest unit tests, assert init-before-render ordering and no-Auth-Key-in-source, and use Detox for the flows only a device can prove. Triggers: test CometChat React Native, mock CometChat SDK jest, detox CometChat, unit test chat screen RN, CI tests for chat."
+license: "MIT"
+compatibility: "React Native >=0.77; Jest; @testing-library/react-native; Detox (e2e)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native testing jest detox mocking ci"
+---
+
+> **Ground truth:** `catalogs/rn-v5.json` + `catalogs/rn-sdk-v4.json`.
+> **Build the feature; do NOT test it unless asked.** Use this skill only when the developer asks for
+> tests. Never add a test framework, e2e suite or CI to a project that did not request one.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "write tests for the chat screen" · "mock CometChat in Jest" · "add Detox coverage for chat"
+
+## Prerequisites & install
+React Native ships Jest. Add the renderer:
+
+```bash
+npm install --save-dev @testing-library/react-native
+```
+
+## Mock the SDK — never let a unit test hit the network
+CometChat opens a websocket and needs real credentials. Mock at the module boundary:
+
+```js
+jest.mock("@cometchat/chat-sdk-react-native", () => ({
+  CometChat: {
+    init: jest.fn().mockResolvedValue(true),
+    login: jest.fn().mockResolvedValue({ getUid: () => "test-uid" }),
+    logout: jest.fn().mockResolvedValue(true),
+    AppSettings: { SUBSCRIPTION_TYPE_ALL_USERS: "ALL_USERS" },
+  },
+}));
+```
+
+The UI Kit also pulls native modules, so mock the peers your test path touches —
+`react-native-gesture-handler`, `react-native-svg`, `react-native-video`,
+`@react-native-async-storage/async-storage`. Without them the failure is a NativeModule error that
+never mentions CometChat: the same confusing shape as a missing install.
+
+## What is worth asserting
+
+**Ordering** — the invariant most likely to regress: `init` resolves before `login`, and no chat
+component renders until login resolves.
+
+**No Auth Key in source** — a cheap grep test that stops a shipped secret ever landing:
+
+```js
+it("has no auth key in source", () => {
+  const src = require("fs").readFileSync("src/config.ts", "utf8");
+  expect(src).not.toMatch(/authKey\s*:\s*["'][A-Za-z0-9]{20,}/);
+});
+```
+
+**Wiring, not rendering** — that `onItemPress` navigates, that `onBack` returns, that an opened
+surface can be closed. Unwired affordances are the defect class worth catching.
+
+Do **not** assert on kit internals — bubble markup, class names, child order. Those change between
+minors, so the test breaks with nothing actually wrong.
+
+## Detox for what only a device proves
+
+| Flow | Why it cannot be a unit test |
+|---|---|
+| composer survives the keyboard | needs a real soft keyboard |
+| hardware back navigates | needs the OS back gesture |
+| gestures respond | proves `GestureHandlerRootView` is wired |
+| release-build startup | catches the gesture-handler import-order crash |
+
+**Calls and push are outside Detox too** — they need real hardware, real permissions and a second
+device. Record them as manual device checks rather than pretending they are automated.
+
+## CI
+Jest with mocks runs anywhere. Detox needs a simulator — heavier, but feasible. Neither can verify
+calls or push, so a green CI run is not evidence that either works.
+
+## Common pitfalls
+1. **Unmocked native peers** — confusing NativeModule errors.
+2. **Asserting kit internals** — breaks on minor upgrades.
+3. **Real credentials in tests** — network flakes and leaked keys.
+4. **Claiming push/calls coverage** from a simulator run.
+5. **Adding tests nobody asked for.**
+
+## Verify it works
+- Tests pass with no network access.
+- No real credentials anywhere in the test tree.
+- `npm run verify:fences:rn-v5` is green.