@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,203 +0,0 @@
-# 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.loginWithAuthToken(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.loginWithAuthToken(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

@@ -1,125 +0,0 @@
-# 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";
-
-// Layout values are the bare string literals "TILE" | "SIDEBAR" | "SPOTLIGHT".
-// There are NO top-level LAYOUT / SESSION_TYPE named exports — the SDK only exports
-// CometChatCalls. (Constants that exist are namespaced statics:
-// CometChatCalls.CALL_MODE.* and CometChatCalls.AUDIO_MODE.* — verified against
-// calls-sdk-react-native skills/session-settings.)
-// Session type is the sessionSettings.sessionType field ('VIDEO' | 'VOICE'), not an enum import.
-
-// Mid-call switch — setLayout takes a bare string literal:
-CometChatCalls.setLayout("SPOTLIGHT"); // "TILE" | "SIDEBAR" | "SPOTLIGHT"
-
-// Listen
-const off = CometChatCalls.addEventListener("onCallLayoutChanged", (layout) => {
-  // ...
-});
-// later: off();  // addEventListener returns the unsubscribe fn
-
-// Hide the kit's change-layout button: it's a SessionSettings OBJECT field
-// (hideChangeLayoutButton), passed to <CometChatCalls.Component />, not a builder method.
-```
-
----
-
-## 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]);
-    const off = CometChatCalls.addEventListener("onCallLayoutChanged", sub);
-    return () => off();
-  }, []);
-
-  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
-
-- [ ] Layout switched via `CometChatCalls.setLayout("…")` (bare string literal)
-- [ ] 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

@@ -1,182 +0,0 @@
-# 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 `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 — `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