@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,134 @@
+# Adding calls to an existing chat integration (Flutter V6 / Bloc)
+
+V6 calls are **bundled** into `cometchat_chat_uikit: ^6.0.0-beta2` — no separate calls package. Toggle on by enabling calling in the UIKit settings.
+
+**Read first:** `cometchat-flutter-v6-calls/SKILL.md` — V6 architecture (Bloc).
+
+---
+
+## Step 1 — Verify chat-uikit cohort
+
+```yaml
+# pubspec.yaml
+dependencies:
+  cometchat_chat_uikit: ^6.0.0-beta2   # V6 — calls bundled
+```
+
+If you see `cometchat_calls_uikit` separately listed, you're on V5 cohort — see `cometchat-flutter-v5-calls/references/add-calls-to-existing-chat.md`.
+
+---
+
+## Step 2 — Enable calling on UIKit init
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  final settings = UIKitSettingsBuilder()
+    ..setAppId(APP_ID)
+    ..setRegion(REGION)
+    ..enableCalling();         // NEW
+
+  await CometChatUIKit.init(uiKitSettings: settings.build());
+  runApp(const MyApp());
+}
+```
+
+That's the entire migration. Calls init internally when chat init succeeds.
+
+---
+
+## Step 3 — iOS + Android native config
+
+Same as V5 (see V5 sister doc) — Info.plist + permissions + ConnectionService don't change between cohorts.
+
+---
+
+## Step 4 — Mount CometChatIncomingCall
+
+```dart
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Stack(
+        children: [
+          BlocProvider(
+            create: (_) => AuthBloc()..add(LoginRequested()),
+            child: const AppRoot(),
+          ),
+          const CometChatIncomingCall(),
+        ],
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Step 5 — Bloc-wrapped login + push registration
+
+```dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  AuthBloc({required this.api}) : super(const AuthState.initial()) {
+    on<LoginRequested>(_onLogin);
+  }
+
+  Future<void> _onLogin(LoginRequested event, Emitter<AuthState> emit) async {
+    try {
+      final user = await CometChatUIKit.login(uid: event.uid, authKey: AUTH_KEY);
+      // No separate CometChatCalls.login in V6 — bundled
+      emit(AuthState.authenticated(user));
+
+      // Register VoIP push tokens after login
+      await context.read<CallPushBloc>().add(RegisterTokens(uid: user.uid));
+    } catch (e) {
+      emit(AuthState.failed(e.toString()));
+    }
+  }
+}
+```
+
+(See `cometchat-flutter-v6-calls/references/server-push-bridge.md` for the CallPushBloc pattern.)
+
+---
+
+## Step 6 — Hangup teardown via Bloc
+
+```dart
+class CallBloc extends Bloc<CallEvent, CallState> {
+  CallBloc() : super(const CallState.idle()) {
+    on<EndCall>(_onEndCall);
+  }
+
+  Future<void> _onEndCall(EndCall event, Emitter<CallState> emit) async {
+    CometChatCalls.leaveSession();
+    await CometChat.endCall(event.sessionId);
+    // V6's bundled flow: no additional FlutterCallkitIncoming step;
+    // the kit handles it
+    emit(const CallState.ended());
+  }
+}
+```
+
+---
+
+## Verification checklist
+
+- [ ] `cometchat_chat_uikit: ^6.0.0-beta2` (or higher V6) in pubspec
+- [ ] `..enableCalling()` chained in UIKitSettingsBuilder
+- [ ] Native config (iOS + Android) same as V5
+- [ ] `CometChatIncomingCall` sibling-overlay at root
+- [ ] VoIP push registration via CallPushBloc post-login
+- [ ] Run `cometchat verify --calls` — should pass
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/add-calls-to-existing-chat.md` — V5 sister (separate calls package)
+- `cometchat-flutter-v6-calls/SKILL.md` — V6 Bloc patterns
+- `cometchat-flutter-v6-calls/references/server-push-bridge.md`

package/skills/cometchat-flutter-v6-calls/references/call-layouts.md

@@ -0,0 +1,102 @@
+# Call layouts on Flutter V6 (Bloc)
+
+Same SDK shape; Bloc-driven layout state.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/call-layouts
+**Read first:** `cometchat-flutter-v5-calls/references/call-layouts.md` — SegmentedButton pattern + SDK API.
+
+---
+
+## Cubit (single-state, no events overhead)
+
+A layout switcher is a great fit for a Cubit since it has only one piece of state with simple updates.
+
+```dart
+class CallLayoutCubit extends Cubit<CallLayout> {
+  CallLayoutCubit() : super(CallLayout.tile);
+
+  void set(CallLayout next) {
+    CometChatCalls.setLayout(next);
+    emit(next);
+  }
+
+  void onSDKChanged(CallLayout next) {
+    emit(next);  // already changed by kit's switcher; just sync
+  }
+}
+```
+
+Hook the SDK event:
+
+```dart
+@override
+void onCallLayoutChanged(CallLayout layout) {
+  context.read<CallLayoutCubit>().onSDKChanged(layout);
+}
+```
+
+---
+
+## Switcher widget
+
+```dart
+class LayoutSwitcher extends StatelessWidget {
+  const LayoutSwitcher({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<CallLayoutCubit, CallLayout>(
+      builder: (context, layout) => SegmentedButton<CallLayout>(
+        segments: const [
+          ButtonSegment(value: CallLayout.tile, label: Text('Tile')),
+          ButtonSegment(value: CallLayout.sidebar, label: Text('Sidebar')),
+          ButtonSegment(value: CallLayout.spotlight, label: Text('Spotlight')),
+        ],
+        selected: {layout},
+        onSelectionChanged: (set) {
+          if (set.isNotEmpty) {
+            context.read<CallLayoutCubit>().set(set.first);
+          }
+        },
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Provide the cubit at call start
+
+```dart
+BlocProvider<CallLayoutCubit>(
+  create: (_) => CallLayoutCubit(),
+  child: const CallScreen(),
+);
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **Using a full Bloc when Cubit fits.** Layout switcher is one-state-update — Cubit avoids the events boilerplate.
+2. **`BlocListener` for switcher rebuild.** Use `BlocBuilder` — switcher *is* a UI that depends on state, not a side-effect.
+
+---
+
+## Verification checklist
+
+- [ ] `CallLayoutCubit` provided above the call screen
+- [ ] `BlocBuilder` wraps the switcher
+- [ ] `onCallLayoutChanged` syncs the cubit
+- [ ] Real-device smoke: switcher cycles all 3 on Android + iOS
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/call-layouts.md` — V5 sister (GetX)
+- `cometchat-flutter-v6-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/call-layouts

package/skills/cometchat-flutter-v6-calls/references/call-session.md

@@ -0,0 +1,229 @@
+# Call session — joinSession with no ringing (Flutter V6 / Bloc)
+
+Bloc-driven adaptation of the upstream sample. Same SDK underneath as V5 (`cometchat_calls_sdk`); the V6 kit (`cometchat_chat_uikit ^6.0.0`) is OPTIONAL for session-only flows.
+
+**Read first:**
+- `cometchat-flutter-v5-calls/references/call-session.md` — V5 sister, canonical SDK API surface (callback shape, `SessionSettingsBuilder`, `SessionStatusListeners`)
+- `cometchat-react-calls/references/call-session.md` — full cross-platform architecture
+
+**Source of truth:** `~/Downloads/calls-sdk/calls-sdk-flutter-5/sample-apps/cometchat-calls-sample-app-flutter/lib/screens/call_screen.dart` (the SDK version is the same; only the state-management primitive differs between v5 GetX and v6 Bloc).
+
+---
+
+## Hard rules
+
+All V5 rules apply (callback API, `SessionSettingsBuilder`, `SessionStatusListeners` interface, `CometChatOngoingCallService.launch/abort`, `SizedBox.expand`, no Chat SDK for session-only). The V6-specific delta is:
+
+1. **Cubit, not full Bloc.** Single 1-state-update flow — Cubit is the right primitive. Don't introduce events + reducer ceremony.
+2. **`BlocConsumer` for auto-pop on idle transition** — combines side-effect (Navigator.pop on terminated) with builder (loading / error / active UI).
+3. **Cubit holds the listener references**, not the widget. `close()` calls `removeSessionStatusListener` + `CometChatOngoingCallService.abort()`.
+
+---
+
+## Cubit
+
+```dart
+import 'package:bloc/bloc.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
+import 'package:equatable/equatable.dart';
+import 'package:flutter/widgets.dart';
+import 'package:permission_handler/permission_handler.dart';
+
+enum CallSessionStatus { idle, requesting, joining, active, leaving, error }
+
+class CallSessionState extends Equatable {
+  final CallSessionStatus status;
+  final Widget? videoWidget;
+  final String? error;
+  const CallSessionState({this.status = CallSessionStatus.idle, this.videoWidget, this.error});
+
+  CallSessionState copyWith({
+    CallSessionStatus? status,
+    Widget? videoWidget,
+    String? error,
+  }) =>
+      CallSessionState(
+        status: status ?? this.status,
+        videoWidget: videoWidget ?? this.videoWidget,
+        error: error ?? this.error,
+      );
+
+  @override
+  List<Object?> get props => [status, videoWidget, error];
+}
+
+class CallSessionCubit extends Cubit<CallSessionState> implements SessionStatusListeners {
+  CallSessionCubit() : super(const CallSessionState());
+
+  CallSession? _callSession;
+
+  Future<void> join(String sessionId) async {
+    if (state.status != CallSessionStatus.idle) return;
+    emit(state.copyWith(status: CallSessionStatus.requesting));
+
+    final cam = await Permission.camera.request();
+    final mic = await Permission.microphone.request();
+    if (!cam.isGranted || !mic.isGranted) {
+      emit(state.copyWith(status: CallSessionStatus.error, error: 'Permission denied'));
+      return;
+    }
+
+    emit(state.copyWith(status: CallSessionStatus.joining));
+
+    final settings = (SessionSettingsBuilder()
+          .setTitle('CometChat Meeting')
+          .startVideoPaused(false)
+          .startAudioMuted(false))
+        .build();
+
+    CometChatCalls.joinSession(
+      sessionId: sessionId,
+      sessionSettings: settings,
+      onSuccess: (Widget? widget) {
+        _callSession = CallSession.getInstance();
+        _callSession?.addSessionStatusListener(this);
+        CometChatOngoingCallService.launch();
+        emit(state.copyWith(status: CallSessionStatus.active, videoWidget: widget));
+      },
+      onError: (CometChatCallsException error) {
+        emit(state.copyWith(status: CallSessionStatus.error, error: error.message ?? 'Failed'));
+      },
+    );
+  }
+
+  Future<void> leave() async {
+    if (state.status == CallSessionStatus.idle) return;
+    emit(state.copyWith(status: CallSessionStatus.leaving));
+    try {
+      await _callSession?.leaveSession();
+    } catch (_) {
+      // best-effort
+    }
+    await CometChatOngoingCallService.abort();
+    emit(const CallSessionState());  // back to idle
+  }
+
+  // --- SessionStatusListeners ---
+  @override
+  void onSessionJoined() {
+    CometChatOngoingCallService.launch();
+  }
+
+  // All termination events funnel through ONE guarded _handleTermination().
+  // The v5 Calls SDK fires onSessionLeft + onConnectionClosed in sequence on
+  // every hangup. Without the guard, abort() + emit() fire 3 times (wasteful
+  // and races with cubit close on rapid leave/rejoin).
+  bool _isTerminating = false;
+  void _handleTermination() {
+    if (_isTerminating) return;
+    _isTerminating = true;
+    CometChatOngoingCallService.abort();
+    emit(const CallSessionState());
+  }
+
+  @override
+  void onSessionLeft() => _handleTermination();
+
+  @override
+  void onConnectionClosed() => _handleTermination();
+
+  @override
+  void onSessionTimedOut() => _handleTermination();
+
+  @override
+  void onConnectionLost() {}
+  @override
+  void onConnectionRestored() {}
+
+  @override
+  Future<void> close() async {
+    _callSession?.removeSessionStatusListener(this);
+    if (state.status != CallSessionStatus.idle) {
+      await CometChatOngoingCallService.abort();
+      try {
+        await _callSession?.leaveSession();
+      } catch (_) {}
+    }
+    return super.close();
+  }
+}
+```
+
+---
+
+## Call room widget
+
+```dart
+class CallRoom extends StatelessWidget {
+  final String sessionId;
+  const CallRoom({super.key, required this.sessionId});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocProvider<CallSessionCubit>(
+      create: (_) => CallSessionCubit()..join(sessionId),
+      child: BlocConsumer<CallSessionCubit, CallSessionState>(
+        listenWhen: (prev, curr) =>
+            prev.status != CallSessionStatus.idle && curr.status == CallSessionStatus.idle,
+        listener: (context, state) => Navigator.of(context).pop(),
+        builder: (context, state) {
+          if (state.status == CallSessionStatus.error) {
+            return Scaffold(
+              backgroundColor: Colors.black,
+              body: Center(child: Text('Error: ${state.error}', style: const TextStyle(color: Colors.white))),
+            );
+          }
+          if (state.status != CallSessionStatus.active || state.videoWidget == null) {
+            return const Scaffold(
+              backgroundColor: Colors.black,
+              body: Center(child: CircularProgressIndicator(color: Colors.white)),
+            );
+          }
+          return Scaffold(
+            backgroundColor: Colors.black,
+            body: SizedBox.expand(child: state.videoWidget),
+          );
+        },
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **Storing the returned widget in the cubit's `_controller` field** as if it were a controller. The `Widget?` IS what you render — there is no controller layer in the v5 Calls SDK.
+2. **Full Bloc with events for a 1-state-update flow.** Cubit fits cleanly.
+3. **`BlocBuilder` instead of `BlocConsumer`.** Need both side-effect (auto-pop) and builder (loading/error UI).
+4. **Forgetting `..join(sessionId)` cascade.** Cubit created but never starts joining.
+5. **Forgetting to call `CometChatOngoingCallService.abort()` in `close()`.** Service notification persists after route pops.
+6. **`CometChatOngoingCallController` / `CometChatOngoingCallView`.** These do not exist in the v5 Calls SDK API. Use the `Widget?` returned by `onSuccess` directly.
+
+---
+
+## Verification checklist
+
+- [ ] Cubit implements `SessionStatusListeners` and registers itself in `onSuccess`
+- [ ] `joinSession` called with `sessionId:`, `sessionSettings:`, `onSuccess:`, `onError:`
+- [ ] Settings built via `SessionSettingsBuilder()`, not `CallSettings`
+- [ ] `BlocProvider` creates cubit and triggers `..join(sessionId)`
+- [ ] `BlocConsumer.listener` pops route on idle transition
+- [ ] Loading / error UI for non-active states
+- [ ] Widget rendered via `SizedBox.expand(child: state.videoWidget)`
+- [ ] `close()` removes listener + aborts ongoing-call service + best-effort leaves
+- [ ] **Standalone session-only:** no `cometchat_chat_sdk` dependency — Calls SDK alone
+- [ ] Real-device smoke: same as V5 sister
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/call-session.md` — V5 sister + canonical SDK API
+- `cometchat-flutter-v6-calls/SKILL.md` — V6 Bloc patterns
+- `cometchat-flutter-v6-calls/references/share-invite.md` — deep-link config
+- Upstream sample — `~/Downloads/calls-sdk/calls-sdk-flutter-5/sample-apps/cometchat-calls-sample-app-flutter/lib/screens/call_screen.dart` (SDK is the same)
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/join-session

package/skills/cometchat-flutter-v6-calls/references/device-management.md

@@ -0,0 +1,99 @@
+# Device management on Flutter V6 (Bloc)
+
+Same SDK API as V5; Bloc-based state.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/device-management
+**Read first:** `cometchat-flutter-v5-calls/references/device-management.md` — SDK shape + flutter_callkit_incoming integration.
+
+---
+
+## SDK API
+
+Same as V5. `CometChatCalls.switchCamera()` and `CometChatCalls.setSpeakerEnabled(bool)`.
+
+---
+
+## Bloc-driven device state
+
+```dart
+class DeviceState extends Equatable {
+  final bool speakerOn;
+  final bool cameraIsBack;
+  const DeviceState({this.speakerOn = false, this.cameraIsBack = false});
+  DeviceState copyWith({bool? speakerOn, bool? cameraIsBack}) =>
+    DeviceState(
+      speakerOn: speakerOn ?? this.speakerOn,
+      cameraIsBack: cameraIsBack ?? this.cameraIsBack,
+    );
+  @override List<Object> get props => [speakerOn, cameraIsBack];
+}
+
+abstract class DeviceEvent {}
+class ToggleSpeaker extends DeviceEvent {}
+class FlipCamera extends DeviceEvent {}
+
+class DeviceBloc extends Bloc<DeviceEvent, DeviceState> {
+  DeviceBloc() : super(const DeviceState()) {
+    on<ToggleSpeaker>((event, emit) {
+      final next = !state.speakerOn;
+      CometChatCalls.setSpeakerEnabled(next);
+      emit(state.copyWith(speakerOn: next));
+    });
+    on<FlipCamera>((event, emit) {
+      CometChatCalls.switchCamera();
+      emit(state.copyWith(cameraIsBack: !state.cameraIsBack));
+    });
+  }
+}
+```
+
+---
+
+## Toggle widgets
+
+```dart
+class SpeakerToggle extends StatelessWidget {
+  const SpeakerToggle({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<DeviceBloc, DeviceState>(
+      buildWhen: (prev, curr) => prev.speakerOn != curr.speakerOn,
+      builder: (context, state) => IconButton(
+        icon: Icon(state.speakerOn ? Icons.volume_up : Icons.hearing),
+        onPressed: () => context.read<DeviceBloc>().add(ToggleSpeaker()),
+        tooltip: state.speakerOn ? 'Switch to earpiece' : 'Switch to speaker',
+      ),
+    );
+  }
+}
+```
+
+`buildWhen` prevents re-rendering on unrelated state changes — important during a video call where rebuild thrash hurts performance.
+
+---
+
+## Anti-patterns
+
+Same as V5; plus V6-specific:
+
+1. **`buildWhen` omitted.** Every state emit re-renders every BlocBuilder.
+2. **Calling SDK methods inside Bloc handlers without try/catch.** Throwing inside the handler crashes the bloc.
+
+---
+
+## Verification checklist
+
+- [ ] DeviceBloc with `ToggleSpeaker` + `FlipCamera` events
+- [ ] BlocBuilder uses `buildWhen` for narrow rebuilds
+- [ ] State is `Equatable` with proper `props`
+- [ ] Real-device smoke: speaker toggle, camera flip both work
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/device-management.md` — V5 sister
+- `cometchat-flutter-v6-calls` SKILL.md
+- `cometchat-flutter-v6-calls/references/raise-hand.md` — Bloc pattern sibling
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/device-management