@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,203 @@
+# Adding calls to an existing chat integration (React Native)
+
+Same shape as web (install SDK, init after chat, add IncomingCall) plus RN-specific work: native modules, CallKeep, VoIP push, foreground service permissions.
+
+**Read first:** `cometchat-react-calls/references/add-calls-to-existing-chat.md` — canonical web steps.
+**See also:** `cometchat-native-calls/SKILL.md` — RN seven hard rules.
+
+---
+
+## Pre-flight
+
+```bash
+grep -E '"@cometchat/(chat-sdk|chat-uikit)-react-native' package.json
+```
+
+Confirm chat SDK + UI Kit RN are present.
+
+---
+
+## Step 1 — Install calls SDK + native peers
+
+```bash
+npm install @cometchat/calls-sdk-react-native@5 \
+  react-native-webrtc \
+  react-native-incall-manager \
+  react-native-callstats \
+  react-native-callkeep \
+  react-native-voip-push-notification \
+  @react-native-firebase/messaging \
+  @react-native-community/netinfo
+
+cd ios && pod install && cd ..
+```
+
+Each native module has its own setup — review the `cometchat-native-calls` SKILL Step 2 for the full list.
+
+---
+
+## Step 2 — iOS: Info.plist + entitlements
+
+```xml
+<!-- ios/<App>/Info.plist -->
+<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>
+```
+
+Enable **Push Notifications** + **Background Modes** (Audio, Voice over IP) in your Xcode target → Signing & Capabilities.
+
+---
+
+## Step 3 — Android: manifest + permissions
+
+```xml
+<!-- android/app/src/main/AndroidManifest.xml -->
+<uses-permission android:name="android.permission.RECORD_AUDIO"/>
+<uses-permission android:name="android.permission.CAMERA"/>
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
+<uses-permission android:name="android.permission.BLUETOOTH"/>
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>
+<uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
+
+<application ...>
+  <service
+    android:name="io.wazo.callkeep.RNCallKeepBackgroundMessagingService"
+    android:foregroundServiceType="microphone|camera"
+    android:exported="false" />
+</application>
+```
+
+`foregroundServiceType` is **mandatory on Android 14+** — the rule is: a foreground service that uses mic/camera must declare those types or the OS kills it.
+
+---
+
+## Step 4 — Init order (chat → calls)
+
+Same pattern as web. In your existing `cometchat-init.ts`:
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+await CometChat.init(APP_ID, settings);
+await CometChatCalls.init({ appId: APP_ID, region: REGION });
+
+// Later, after CometChat.login:
+await CometChatCalls.login(authToken);
+```
+
+---
+
+## Step 5 — Mount IncomingCall at root
+
+```tsx
+// App.tsx
+import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
+
+function App() {
+  return (
+    <NavigationContainer>
+      <RootNavigator />
+      <CometChatIncomingCall />   {/* Sibling of NavigationContainer's content */}
+    </NavigationContainer>
+  );
+}
+```
+
+---
+
+## Step 6 — CallKeep + VoIP push setup
+
+```tsx
+import RNCallKeep from "react-native-callkeep";
+import VoipPushNotification from "react-native-voip-push-notification";
+import { Platform } from "react-native";
+
+const callKeepOptions = {
+  ios: {
+    appName: "Your App",
+    supportsVideo: true,
+    maximumCallGroups: "1",
+    maximumCallsPerCallGroup: "1",
+  },
+  android: {
+    alertTitle: "Permissions required",
+    alertDescription: "This app needs phone permissions to display incoming calls.",
+    cancelButton: "Cancel",
+    okButton: "OK",
+    additionalPermissions: [],
+    foregroundService: {
+      channelId: "your-app-call-channel",
+      channelName: "Calls",
+      notificationTitle: "Active call",
+      notificationIcon: "ic_launcher",
+    },
+  },
+};
+
+await RNCallKeep.setup(callKeepOptions);
+RNCallKeep.setAvailable(true);
+
+// iOS PushKit
+if (Platform.OS === "ios") {
+  VoipPushNotification.addEventListener("register", async (token) => {
+    await api.registerCallToken({ uid: currentUserUid, platform: "ios-voip", token });
+  });
+  VoipPushNotification.registerVoipToken();
+}
+```
+
+See `cometchat-native-calls/references/server-push-bridge.md` for the server side.
+
+---
+
+## Step 7 — Wire hangup teardown
+
+When a call ends, both `CometChat` and `CometChatCalls` need cleanup:
+
+```ts
+async function endCall() {
+  CometChatCalls.leaveSession();   // calls SDK
+  await CometChat.endCall(sessionId);  // chat SDK call record
+  RNCallKeep.endCall(callKeepUuid);    // OS-level UI dismissal
+}
+```
+
+Skipping any of these leaves zombies — call still showing in the OS as "active" or chat-side call record stuck in "ongoing."
+
+---
+
+## Verification checklist
+
+- [ ] All native peer packages in package.json
+- [ ] `pod install` succeeded (no module-not-found at link time)
+- [ ] Info.plist + AndroidManifest permissions in place
+- [ ] `foregroundServiceType` declared (Android 14+)
+- [ ] Calls init AFTER chat init
+- [ ] `CometChatCalls.login(authToken)` after chat login
+- [ ] CallKeep `setup` runs on app start (post-login)
+- [ ] VoIP token registration triggered on iOS
+- [ ] FCM token registration triggered on Android
+- [ ] `CometChatIncomingCall` mounted at root
+- [ ] Hangup teardown calls all 3: `CometChatCalls.leaveSession`, `CometChat.endCall`, `RNCallKeep.endCall`
+- [ ] Real-device smoke: backgrounded incoming call rings on lock screen
+- [ ] Run `cometchat verify --calls` — should pass all 20 checks
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/add-calls-to-existing-chat.md` — canonical (web, no native modules)
+- `cometchat-native-calls/SKILL.md` — RN seven hard rules
+- `cometchat-native-calls/references/server-push-bridge.md` — server-side push routing

package/skills/cometchat-native-calls/references/call-layouts.md

@@ -0,0 +1,124 @@
+# Call layouts on React Native
+
+Same SDK as web (TILE/SIDEBAR/SPOTLIGHT). RN-specific: layout switcher must be a touchable, not a `<button>`; orientation changes are common in mobile so layout-on-rotate is a real consideration.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/call-layouts
+**Read first:** `cometchat-react-calls/references/call-layouts.md` — layout matrix + when to lock.
+
+---
+
+## SDK API
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+const callSettings = new CallSettingsBuilder()
+  .setSessionType(CometChatCalls.constants.SESSION_TYPE.VIDEO)
+  .setLayout(CometChatCalls.constants.LAYOUT.TILE)
+  .build();
+
+// Mid-call switch
+CometChatCalls.setLayout(CometChatCalls.constants.LAYOUT.SPOTLIGHT);
+
+// Listen
+CometChatCalls.addEventListener("onCallLayoutChanged", (layout) => {
+  // ...
+});
+
+// Hide kit switcher
+const settings2 = new CallSettingsBuilder()
+  .setHideChangeLayoutButton(true)
+  .build();
+```
+
+---
+
+## RN switcher component
+
+```tsx
+import { Pressable, View, Text, StyleSheet } from "react-native";
+import { useState, useEffect } from "react";
+
+const LAYOUTS = ["TILE", "SIDEBAR", "SPOTLIGHT"] as const;
+
+export function LayoutSwitcher() {
+  const [layout, setLayout] = useState<typeof LAYOUTS[number]>("TILE");
+
+  useEffect(() => {
+    const sub = (next: string) => setLayout(next as typeof LAYOUTS[number]);
+    CometChatCalls.addEventListener("onCallLayoutChanged", sub);
+    return () => CometChatCalls.removeEventListener("onCallLayoutChanged", sub);
+  }, []);
+
+  return (
+    <View style={styles.row} accessibilityRole="radiogroup">
+      {LAYOUTS.map((opt) => (
+        <Pressable
+          key={opt}
+          accessibilityRole="radio"
+          accessibilityState={{ selected: layout === opt }}
+          accessibilityLabel={`${opt} layout`}
+          onPress={() => {
+            CometChatCalls.setLayout(opt);
+            setLayout(opt);
+          }}
+          style={[styles.btn, layout === opt && styles.btnActive]}
+        >
+          <Text>{opt}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+```
+
+---
+
+## Orientation-aware default
+
+Most users prefer SPOTLIGHT in portrait (one big tile + small thumbnails) and TILE in landscape (grid uses width). Wire it via `useWindowDimensions`:
+
+```tsx
+import { useWindowDimensions } from "react-native";
+
+function CallScreen() {
+  const { width, height } = useWindowDimensions();
+  const isLandscape = width > height;
+
+  useEffect(() => {
+    CometChatCalls.setLayout(isLandscape ? "TILE" : "SPOTLIGHT");
+  }, [isLandscape]);
+
+  // ...
+}
+```
+
+Only do this if user-testing shows orientation-change layout flips are desired. For most apps a stable layout is calmer.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus RN-specific:
+
+1. **`<TouchableHighlight>` without `accessibilityRole`.** TalkBack/VoiceOver can't announce the radio group.
+2. **`Modal` for layout switcher.** Modal blocks the call surface — defeats in-call layout switching. Use bottom-sheet or inline pill.
+3. **Re-rendering the call surface on layout change.** Causes flicker. The SDK's `setLayout` is internal-only — don't gate the surface JSX on layout state.
+
+---
+
+## Verification checklist
+
+- [ ] Initial layout via `setLayout()` on the builder
+- [ ] Switcher uses `Pressable` with `accessibilityRole="radio"`
+- [ ] Layout listener cleaned up on unmount
+- [ ] Orientation change handled (or explicitly stable)
+- [ ] Real-device smoke (iOS + Android): switcher cycles through all 3 layouts
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/call-layouts.md` — sister
+- `cometchat-native-calls` SKILL.md — seven hard rules
+- Canonical docs: https://www.cometchat.com/docs/calls/react-native/call-layouts

package/skills/cometchat-native-calls/references/call-session.md

@@ -0,0 +1,182 @@
+# Call session — joinSession with no ringing (React Native)
+
+Server-generated sessionId, both parties enter it; RN uses a **declarative `<CometChatCalls.Component>` render primitive**, NOT the imperative `joinSession(token, settings, container)` web pattern. Customer-validated against `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`.
+
+**Read first:** `cometchat-react-calls/references/call-session.md` — full architecture (sessionId strategies, server-side authorization, token generation). Then come back here for the RN-specific render shape.
+
+---
+
+## Hard rules (RN-specific overrides on top of the cross-platform rules)
+
+1. **Render path, not imperative call.** RN's session mode uses `<CometChatCalls.Component callToken={token} />` — a React Native component that handles native rendering, permissions, and lifecycle internally. Do NOT call `CometChatCalls.joinSession(token, settings, viewRef)` — that is the web SDK shape and does not exist on RN session mode.
+2. **State machine: `inMeeting` + `callToken`.** First effect generates the token when `inMeeting && sessionId` flips true; the component renders the call surface only when BOTH `inMeeting && callToken` are set.
+3. **`onConnectionClosed`** is the cleanup event, not `onSessionLeft`. Fires on ANY termination.
+4. **`CometChatCalls.init({ appId, region, authKey })`** — pass `authKey` at init time so `CometChatCalls.login(uid)` needs no second arg. Matches the sample.
+5. **For standalone session-only integrations, the Chat SDK is OPTIONAL.** The upstream RN sample never imports `@cometchat/chat-sdk-react-native`. Keep dual-SDK only for additive (chat + calls) integrations.
+6. **Permissions must be requested before mounting `<CometChatCalls.Component>`.** RN does not have browser auto-prompts; iOS Info.plist + Android manifest entries are necessary but not sufficient — you must `request()` at runtime via `react-native-permissions` or `PermissionsAndroid`.
+
+---
+
+## Component pattern (signals-style state + render switch)
+
+```tsx
+import { useState, useEffect } from 'react';
+import { View, SafeAreaView } from 'react-native';
+import { CometChatCalls } from '@cometchat/calls-sdk-react-native';
+
+function CallRoom({ sessionId }: { sessionId: string }) {
+  const [inMeeting, setInMeeting] = useState(false);
+  const [callToken, setCallToken] = useState<string | null>(null);
+
+  // Auto-join once we have a sessionId.
+  useEffect(() => {
+    if (sessionId) setInMeeting(true);
+  }, [sessionId]);
+
+  // Generate token when we flip into the meeting.
+  useEffect(() => {
+    if (inMeeting && sessionId) {
+      CometChatCalls.generateToken(sessionId).then(({ token }) => {
+        setCallToken(token);
+      });
+    }
+  }, [inMeeting, sessionId]);
+
+  // Reset state when the SDK reports the connection closed.
+  useEffect(() => {
+    const off = CometChatCalls.addEventListener('onConnectionClosed', () => {
+      setInMeeting(false);
+      setCallToken(null);
+    });
+    return () => off();
+  }, []);
+
+  if (inMeeting && callToken) {
+    return (
+      <SafeAreaView style={{ flex: 1, backgroundColor: '#141414' }}>
+        <CometChatCalls.Component callToken={callToken} />
+      </SafeAreaView>
+    );
+  }
+
+  return null; // or your pre-call lobby UI
+}
+```
+
+**Why this shape:**
+
+- **`<CometChatCalls.Component callToken={...} />`** — the SDK's native React Native component handles the entire WebRTC lifecycle (peer connection, layout, controls, leave button). You don't pass settings; you don't manage a ref. The component IS the call surface.
+- **`inMeeting && callToken` two-state gate** — token generation is async; rendering the call component before the token exists shows an empty call surface. Gate on both.
+- **`onConnectionClosed`** — fires on ANY termination (peer left, network died, user hit the SDK's Leave button). Reset state on this, not on a separate `onSessionLeft`.
+- **Container is `SafeAreaView`, not a `View` with measurable dimensions.** The Component sizes itself; wrapping in a non-flex container clips the call UI.
+
+---
+
+## Init + login (Calls SDK only, no Chat SDK for session-only)
+
+```tsx
+// App.tsx — or wherever you bootstrap
+import { CometChatCalls } from '@cometchat/calls-sdk-react-native';
+
+useEffect(() => {
+  CometChatCalls.init({
+    appId: APP_ID,
+    region: REGION,
+    authKey: AUTH_KEY,
+  }).then(({ error }) => {
+    if (error) console.error('Calls init failed', error);
+  });
+}, []);
+
+// Login screen
+CometChatCalls.login(uid).then((user) => {
+  // user is the logged-in User_2; navigate to JoinSession
+});
+```
+
+---
+
+## Deep-link routing for meeting URLs
+
+Configure `react-navigation`'s `linking`:
+
+```tsx
+const linking = {
+  prefixes: ['https://yourapp.com', 'yourapp://'],
+  config: {
+    screens: {
+      CallRoom: 'meet/:sessionId',
+    },
+  },
+};
+
+<NavigationContainer linking={linking}>...</NavigationContainer>
+```
+
+- **iOS:** enable Associated Domains entitlement (`applinks:yourapp.com`).
+- **Android:** add `<intent-filter android:autoVerify="true">` to `AndroidManifest.xml` for the meet path.
+
+See `share-invite.md` for full deep-link config.
+
+---
+
+## Permission request before joining
+
+RN does not have browser auto-prompts. Request explicitly before flipping `inMeeting`:
+
+```ts
+import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
+import { Platform } from 'react-native';
+
+async function ensureCallPermissions() {
+  const cam = await request(
+    Platform.OS === 'ios' ? PERMISSIONS.IOS.CAMERA : PERMISSIONS.ANDROID.CAMERA,
+  );
+  const mic = await request(
+    Platform.OS === 'ios' ? PERMISSIONS.IOS.MICROPHONE : PERMISSIONS.ANDROID.RECORD_AUDIO,
+  );
+  if (cam !== RESULTS.GRANTED || mic !== RESULTS.GRANTED) {
+    throw new Error('Camera/microphone permission denied');
+  }
+}
+```
+
+iOS `Info.plist`: `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`. Android `AndroidManifest.xml`: `<uses-permission android:name="android.permission.CAMERA" />`, `<uses-permission android:name="android.permission.RECORD_AUDIO" />`.
+
+---
+
+## Anti-patterns
+
+1. **Calling `CometChatCalls.joinSession(token, settings, viewRef)`.** That is the WEB SDK shape; RN session mode does not have this method. Use `<CometChatCalls.Component callToken={...} />` instead.
+2. **Passing settings as a second arg anywhere.** RN session mode does not take settings — the component picks defaults.
+3. **Rendering `<CometChatCalls.Component>` before the token resolves.** Empty call surface; user thinks the app is broken. Gate on `inMeeting && callToken`.
+4. **Skipping the permission request.** First mount of the call component crashes when iOS asks for camera/mic if `NSCameraUsageDescription` is missing; on Android, the surface mounts but media stays muted.
+5. **No `onConnectionClosed` listener.** User taps the SDK's in-call Leave button → media stops but `inMeeting` stays true → can't navigate away cleanly.
+6. **Initializing Chat SDK for a session-only integration.** Wastes time and adds two extra failure modes. Drop `CometChat.init` / `CometChat.login` entirely for standalone session apps.
+7. **Wrapping `<CometChatCalls.Component>` in a non-flex container.** Call UI clips to 0×0. Use `SafeAreaView` with `flex: 1` or a `View` with `flex: 1`.
+
+---
+
+## Verification checklist
+
+- [ ] Container is `SafeAreaView` or `View` with `flex: 1`
+- [ ] Render path uses `<CometChatCalls.Component callToken={callToken} />`, NOT `joinSession(token, settings, viewRef)`
+- [ ] Gate on `inMeeting && callToken` (both, not either)
+- [ ] `onConnectionClosed` listener resets both `inMeeting` and `callToken` to false/null
+- [ ] Camera + microphone permissions requested at runtime BEFORE flipping `inMeeting`
+- [ ] iOS `Info.plist` has `NSCameraUsageDescription` + `NSMicrophoneUsageDescription`
+- [ ] Android `AndroidManifest.xml` has `CAMERA` + `RECORD_AUDIO` permissions
+- [ ] Deep-link config + native intent filters in place
+- [ ] **Standalone session-only:** no `CometChat.init` / `CometChat.login` — Calls SDK alone
+- [ ] **Additive (chat + calls):** dual-SDK contract preserved (Chat first, then Calls)
+- [ ] Real-device smoke: tap meeting link in WhatsApp → app opens at `/meet/:sessionId` → call component mounts → media flows
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server authorization)
+- `cometchat-native-calls/SKILL.md` — RN seven hard rules
+- `cometchat-native-calls/references/share-invite.md` — deep-link config
+- Upstream RN sample — `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`
+- Canonical docs: https://www.cometchat.com/docs/calls/react-native/join-session