@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-flutter-v6-calls/references/ringing-integration.md

@@ -0,0 +1,171 @@
+# Ringing — call signaling with custom UI (Flutter V6 / Bloc)
+
+Same SDK shape; Bloc-driven state instead of GetX.
+
+**Read first:**
+- `cometchat-flutter-v5-calls/references/ringing-integration.md` — V5 sister (GetX patterns)
+- `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules
+
+---
+
+## Bloc
+
+```dart
+class CallSignalingState extends Equatable {
+  final Call? incoming;
+  final Call? outgoing;
+  final String? activeSessionId;
+
+  const CallSignalingState({this.incoming, this.outgoing, this.activeSessionId});
+  CallSignalingState copyWith({Call? incoming, Call? outgoing, String? activeSessionId}) =>
+      CallSignalingState(
+        incoming: incoming ?? this.incoming,
+        outgoing: outgoing ?? this.outgoing,
+        activeSessionId: activeSessionId ?? this.activeSessionId,
+      );
+  CallSignalingState clear() => const CallSignalingState();
+  @override
+  List<Object?> get props => [incoming?.sessionId, outgoing?.sessionId, activeSessionId];
+}
+
+abstract class CallSignalingEvent {}
+class _IncomingReceived extends CallSignalingEvent { final Call call; _IncomingReceived(this.call); }
+class _OutgoingAccepted extends CallSignalingEvent { final Call call; _OutgoingAccepted(this.call); }
+class _OutgoingRejected extends CallSignalingEvent {}
+class _IncomingCancelled extends CallSignalingEvent {}
+class _CallEnded extends CallSignalingEvent {}
+class InitiateCall extends CallSignalingEvent { final String receiverUid; final String type; InitiateCall(this.receiverUid, {this.type = 'video'}); }
+class AcceptCall extends CallSignalingEvent { final Call call; AcceptCall(this.call); }
+class RejectCall extends CallSignalingEvent { final Call call; RejectCall(this.call); }
+
+class CallSignalingBloc extends Bloc<CallSignalingEvent, CallSignalingState> implements CallListener {
+  static const _listenerId = 'app';
+
+  CallSignalingBloc() : super(const CallSignalingState()) {
+    on<_IncomingReceived>((e, emit) => emit(state.copyWith(incoming: e.call)));
+    on<_OutgoingAccepted>((e, emit) => emit(state.copyWith(outgoing: null, activeSessionId: e.call.sessionId)));
+    on<_OutgoingRejected>((_, emit) => emit(state.copyWith(outgoing: null)));
+    on<_IncomingCancelled>((_, emit) => emit(state.copyWith(incoming: null)));
+    on<_CallEnded>((_, emit) => emit(state.clear()));
+    on<InitiateCall>(_onInitiate);
+    on<AcceptCall>(_onAccept);
+    on<RejectCall>(_onReject);
+
+    CometChat.addCallListener(_listenerId, this);
+  }
+
+  @override
+  void onIncomingCallReceived(Call call) => add(_IncomingReceived(call));
+  @override
+  void onOutgoingCallAccepted(Call call) => add(_OutgoingAccepted(call));
+  @override
+  void onOutgoingCallRejected(Call call) => add(_OutgoingRejected());
+  @override
+  void onIncomingCallCancelled(Call call) => add(_IncomingCancelled());
+  @override
+  void onCallEndedMessageReceived(Call call) => add(_CallEnded());
+
+  Future<void> _onInitiate(InitiateCall e, Emitter<CallSignalingState> emit) async {
+    final call = Call(
+      receiverUid: e.receiverUid,
+      callType: e.type == 'video' ? CometChatCallType.video : CometChatCallType.audio,
+      receiverType: CometChatReceiverType.user,
+    );
+    final result = await CometChat.initiateCall(call: call);
+    if (result is Call) emit(state.copyWith(outgoing: result));
+  }
+
+  Future<void> _onAccept(AcceptCall e, Emitter<CallSignalingState> emit) async {
+    final result = await CometChat.acceptCall(sessionId: e.call.sessionId!);
+    if (result is Call) emit(state.copyWith(incoming: null, activeSessionId: result.sessionId));
+  }
+
+  Future<void> _onReject(RejectCall e, Emitter<CallSignalingState> emit) async {
+    await CometChat.rejectCall(sessionId: e.call.sessionId!, status: CallStatus.rejected);
+    emit(state.copyWith(incoming: null));
+  }
+
+  @override
+  Future<void> close() {
+    CometChat.removeCallListener(_listenerId);
+    return super.close();
+  }
+}
+```
+
+---
+
+## Provide above the router
+
+```dart
+BlocProvider<CallSignalingBloc>(
+  create: (_) => CallSignalingBloc(),
+  child: MaterialApp.router(...),
+);
+```
+
+---
+
+## Incoming-call overlay
+
+```dart
+class IncomingCallOverlay extends StatelessWidget {
+  const IncomingCallOverlay({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<CallSignalingBloc, CallSignalingState>(
+      buildWhen: (prev, curr) => prev.incoming?.sessionId != curr.incoming?.sessionId,
+      builder: (context, state) {
+        final call = state.incoming;
+        if (call == null) return const SizedBox.shrink();
+        // Same UI as V5 sister; replace ctrl.accept/reject with bloc.add(...)
+        return Material(/* ... see V5 sister ... */);
+      },
+    );
+  }
+}
+```
+
+Mount in `MaterialApp.builder`:
+
+```dart
+MaterialApp.router(
+  builder: (context, child) => Stack(
+    children: [
+      child ?? const SizedBox.shrink(),
+      const IncomingCallOverlay(),
+    ],
+  ),
+  routerConfig: ...,
+);
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **`BlocBuilder` without `buildWhen`.** Rebuilds on every state change — listener events for outgoing/active also retrigger incoming UI.
+2. **Calling SDK methods from UI directly.** Adds back to bloc — use `bloc.add(InitiateCall(...))`.
+3. **Provider scoped to a feature module.** Backgrounded ring path can't find the bloc when push fires.
+
+---
+
+## Verification checklist
+
+- [ ] `BlocProvider<CallSignalingBloc>` above `MaterialApp`
+- [ ] `IncomingCallOverlay` in `MaterialApp.builder`'s Stack
+- [ ] `BlocBuilder` uses `buildWhen` to scope rebuilds to `incoming` changes
+- [ ] `close()` calls `removeCallListener`
+- [ ] Real-device smoke: same as V5 sister
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/ringing-integration.md` — V5 sister (GetX)
+- `cometchat-flutter-v6-calls/SKILL.md` — V6 Bloc patterns
+- `cometchat-flutter-v6-calls/references/server-push-bridge.md` — backgrounded ring
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/ringing

package/skills/cometchat-flutter-v6-calls/references/server-push-bridge.md

@@ -0,0 +1,93 @@
+# Server-side push routing for Flutter V6 (iOS PushKit + Android FCM)
+
+V6 uses the same server templates and platform plugins as V5. The only V6-specific delta is wrapping token registration in a Bloc.
+
+**Canonical docs:**
+- iOS: `cometchat-ios-calls/references/server-apns-pushkit.md`
+- Android: `cometchat-android-v5-calls/references/server-fcm-voip.md`
+- Read first: `cometchat-flutter-v5-calls/references/server-push-bridge.md` — Flutter token registration patterns.
+
+---
+
+## Bloc-style token registration
+
+```dart
+class CallPushBloc extends Bloc<CallPushEvent, CallPushState> {
+  CallPushBloc({required this.api}) : super(const CallPushState.idle()) {
+    on<RegisterTokens>(_onRegister);
+  }
+  final Api api;
+
+  Future<void> _onRegister(RegisterTokens event, Emitter<CallPushState> emit) async {
+    emit(const CallPushState.registering());
+    try {
+      if (Platform.isIOS) {
+        final voip = FlutterVoipPushKit();
+        voip.onTokenRefresh.listen((token) {
+          api.registerCallToken(uid: event.uid, platform: 'ios-voip', token: token);
+        });
+        await voip.configure();
+      } else if (Platform.isAndroid) {
+        final messaging = FirebaseMessaging.instance;
+        await messaging.requestPermission();
+        final token = await messaging.getToken();
+        if (token != null) {
+          await api.registerCallToken(uid: event.uid, platform: 'android-fcm', token: token);
+        }
+        messaging.onTokenRefresh.listen((t) {
+          api.registerCallToken(uid: event.uid, platform: 'android-fcm', token: t);
+        });
+      }
+      emit(const CallPushState.registered());
+    } catch (err) {
+      emit(CallPushState.failed(err.toString()));
+    }
+  }
+}
+```
+
+Dispatch after login completes:
+
+```dart
+BlocListener<AuthBloc, AuthState>(
+  listener: (context, state) {
+    if (state is Authenticated) {
+      context.read<CallPushBloc>().add(RegisterTokens(uid: state.uid));
+    }
+  },
+  child: const CallSurface(),
+);
+```
+
+---
+
+## Server-side: unchanged from V5
+
+Identical to V5 — same APNs PushKit + FCM HTTP v1 templates.
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **Registering pushes in `main()` before MultiBlocProvider.** No bloc available; can't dispatch.
+2. **Adding `RegisterTokens` from `BlocBuilder`.** BlocBuilder is for UI rebuilds. Use `BlocListener` for one-shot side effects.
+
+---
+
+## Verification checklist
+
+- [ ] `CallPushBloc` provided above the auth flow
+- [ ] BlocListener triggers `RegisterTokens` post-login
+- [ ] Server templates wired (see V5 sister)
+- [ ] Real-device smoke: both iOS and Android ring
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/server-push-bridge.md` — V5 sister (token registration patterns)
+- `cometchat-ios-calls/references/server-apns-pushkit.md` — iOS canonical
+- `cometchat-android-v5-calls/references/server-fcm-voip.md` — Android canonical
+- `cometchat-flutter-v6-calls` SKILL.md

package/skills/cometchat-flutter-v6-calls/references/share-invite.md

@@ -0,0 +1,102 @@
+# Share invite on Flutter V6 (Bloc)
+
+Same SDK + share_plus. V6-specific: wrap share state in a Cubit so the UI can disable the button while a share is in flight.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/share-invite
+**Read first:** `cometchat-flutter-v5-calls/references/share-invite.md` — share_plus + deep-link config.
+
+---
+
+## Cubit
+
+```dart
+class ShareInviteCubit extends Cubit<bool> {
+  ShareInviteCubit() : super(false);  // false = idle, true = sharing
+
+  Future<void> share(String sessionId, {Rect? origin}) async {
+    if (state) return;  // debounce
+    emit(true);
+    try {
+      final url = 'https://yourapp.com/call/$sessionId';
+      await Share.share(
+        "I'm on a call — tap to join.\n$url",
+        subject: 'Join my call',
+        sharePositionOrigin: origin,
+      );
+    } finally {
+      emit(false);
+    }
+  }
+}
+```
+
+The boolean state is enough; we don't need a sealed-class state hierarchy here.
+
+---
+
+## Bridge from SDK event
+
+```dart
+@override
+void onShareInviteButtonClicked() {
+  context.read<ShareInviteCubit>().share(sessionId);
+}
+```
+
+---
+
+## App-built share button
+
+```dart
+class ShareInviteButton extends StatelessWidget {
+  final String sessionId;
+  const ShareInviteButton({super.key, required this.sessionId});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<ShareInviteCubit, bool>(
+      builder: (context, sharing) => IconButton(
+        icon: sharing
+          ? const SizedBox(width: 24, height: 24, child: CircularProgressIndicator(strokeWidth: 2))
+          : const Icon(Icons.share),
+        onPressed: sharing
+          ? null
+          : () {
+              final box = context.findRenderObject() as RenderBox?;
+              context.read<ShareInviteCubit>().share(
+                sessionId,
+                origin: box != null ? box.localToGlobal(Offset.zero) & box.size : null,
+              );
+            },
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **Full Bloc with events for a 1-state-update flow.** Cubit fits cleanly.
+2. **Forgetting `try/finally` around `Share.share`.** If share throws, button stays in disabled state forever.
+
+---
+
+## Verification checklist
+
+- [ ] `ShareInviteCubit` provided above call screen
+- [ ] Button disabled while sharing (BlocBuilder)
+- [ ] iPad anchor passed via `sharePositionOrigin`
+- [ ] `try/finally` ensures cubit resets even on error
+- [ ] Real-device smoke: same as V5
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/share-invite.md` — V5 sister
+- `cometchat-flutter-v6-calls` SKILL.md
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/share-invite

package/skills/cometchat-flutter-v6-components/SKILL.md

@@ -8,7 +8,7 @@ description: >
   bubbles, list base, search, status indicator).
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter >=2.5.0"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-conversations/SKILL.md

@@ -10,7 +10,7 @@ description: >
   Also use when the user asks about showing a list of chats or recent conversations.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter_bloc ^8.1.0"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-core/SKILL.md

@@ -11,7 +11,7 @@ description: >
   UIKit code, even simple widget usage.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter_bloc ^8.1.0"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-customization/SKILL.md

@@ -7,7 +7,7 @@ description: >
   message actions, or custom message types.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-events/SKILL.md

@@ -13,7 +13,7 @@ description: >
   or any real-time update handling in CometChat.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; cometchat_sdk ^4.1.2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-features/SKILL.md

@@ -8,7 +8,7 @@ description: >
   and what needs manual dashboard configuration (third-party API keys).
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-messages/SKILL.md

@@ -13,7 +13,7 @@ description: >
   the user asks about building a chat screen, message input, or message display.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter_bloc ^8.1.0"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-migration/SKILL.md

@@ -9,7 +9,7 @@ description: >
   like GetBuilder, Get.put, Get.find, PageManager, BuilderSettings, or CometChatCallingExtension.
 license: "MIT"
 compatibility: "cometchat_chat_uikit 6.0.0-beta2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-placement/SKILL.md

@@ -10,7 +10,7 @@ description: >
   "Scaffold layout", or "keyboard handling".
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter >=2.5.0"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"

package/skills/cometchat-flutter-v6-production/SKILL.md

@@ -7,7 +7,7 @@ description: >
   a CometChat Flutter app for production deployment.
 license: "MIT"
 compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+allowed-tools: "shell, file-read, file-search, file-list, grep"
 metadata:
   author: "CometChat"
   version: "3.0.0"