Cometchat Flutter V6 Core

Ground truth: cometchat_chat_uikit@6 (6.1.0) + cometchat_sdk@^5.0.6. Every CometChat* symbol here is in catalogs/flutter-v6.json — compiler-verified against the published package. Signatures marked [verified] were compiled because the docs were wrong, or (for initFromSettings) deliberately silent (DOCS-BACKLOG.md PART 4): trust this file for those, fetch the rest via references/docs-map.md. THIN map loaded every run; depth in references/*.

<!-- core is the companion the other flutter v6 skills read; it has no Companion block of its own. -->

Use this skill when

"add chat to my Flutter app", "integrate CometChat in Flutter", "set up CometChat credentials", "show a conversations + messages screen". An unscoped "add chat" means a production-ready core surface — a CometChatConversations screen pushing a message screen, with threaded replies and search wired, in Scaffold/SafeArea, keyboard-safe, every screen popping back — NOT a two-widget demo, NOT the whole tab-based app (see the golden path). It grows on request → cometchat-flutter-v6-placement.

Install

flutter pub add cometchat_chat_uikit

Pin the major in pubspec.yaml — cometchat_chat_uikit: ^6.1.0 (a bare any can resolve across majors). The Chat SDK (cometchat_sdk) comes transitively and is re-exported by the kit barrel — do NOT add it separately unless you import SDK-only paths. Voice/video calling = a settings flag + native config (cometchat_calls_sdk is already a transitive kit dependency — see below) → cometchat-flutter-v6-calls.

Platform minimums — Android minSdk = 26 in android/app/build.gradle.kts; iOS platform :ios, '15.1' in ios/Podfile. The getting-started page says 24 / 13.0 and both are too low (DOCS-BACKLOG D7). The kit's own AAR allows 21, but transitive deps set the real floor and this one is not optional: cometchat_chat_uikit depends on cometchat_calls_sdk unconditionally — it sits in the main dependencies: block — and that package pins minSdkVersion 26 / platform :ios, '15.1' (5.0.7). Gradle and CocoaPods take the maximum across the graph, so a lower value is a build error whether or not the app uses calling.

Setup & credentials (essentials — full detail: references/setup-credentials.md)

1. Detect by READING the repo — pubspec.yaml + lockfile (deps and the kit major), lib/main.dart, state management, navigation, and how config is handled. Reuse an existing .cometchat/config.json or settings asset (skip re-setup). Signal table: references/setup-credentials.md.
2. version_conflict — STOP if the project already has cometchat_chat_uikit v5 (or any non-v6 major); reconcile first, never mix majors (RULES.md). A v5 project that wants v6 → cometchat-flutter-v6-migration.
3. Credentials — OFFER the dashboard fetch FIRST; never default to "paste it yourself." When App ID / Region / Auth Key are missing, offer (a) fetch from your dashboard (recommended) — load the CLI on demand, pick an EXISTING app (never auto-create) — or (b) manual paste. Then the SKILL writes cometchat-settings.json (§4) from those creds; the CLI is dashboard/API-only and never writes Dart (RULES.md §21). Never defer credentials to a "add them yourself" TODO. Exact commands + the app-picker flow: references/setup-credentials.md.
4. Write the settings asset + register it — commit only a placeholder (no real Auth Key) and do not gitignore it (a registered asset must exist or a fresh-clone flutter build fails — see the note in §Integration ordering); never echo the Auth Key. Prod → server-minted auth token, not the Auth Key.
5. Authorize = init then login both hit onSuccess. An auth error is almost always the wrong Region.

Integration ordering (BAKED — invariant; docs: init must complete before login, login before any widget)

initFromSettings() once at startup → login(UID) after init succeeds → only THEN render any CometChat* widget.

Init via initFromSettings — the file-based, telemetry-attributed path (RULES.md §5). It reads a cometchat-settings.json asset and persists integrationSource="ai-agent". Flutter's signature takes NO settings argument (unlike web, which passes a settings object) — the file IS the input:

// [verified vs 6.1.0] — INTENTIONALLY undocumented upstream (@nodoc, owner decision:
// DOCS-BACKLOG F4 WONTFIX). Prefer it over the docs' UIKitSettingsBuilder + init()
// path, which loses telemetry attribution. The shape below is the contract.
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

await CometChatUIKit.initFromSettings(
  onSuccess: (String message) => debugPrint('CometChat initialized'),
  onError: (CometChatException e) => debugPrint('Init failed: ${e.message}'),
);

cometchat-settings.json at the project root, registered in pubspec.yaml under flutter: assets::

{
  "appId": "APP_ID",
  "region": "REGION",
  "credentials": { "authKey": "AUTH_KEY" },
  "uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": false },
  "chatSDK": { "autoEstablishSocketConnection": true }
}

Keys are read exactly as above. uiKit.enableCalling is the only way to turn calling on via this path (UIKitSettings defaults it to false) — leave it false until the user asks for calls. credentials.authKey is dev-only; omit it for production and log in with a server-minted token. Make a fresh clone build. A file registered under flutter: assets: MUST exist at build time or flutter build bundle fails with "No file or variants found for asset: cometchat-settings.json." So do not gitignore the registered asset. Instead commit a placeholder cometchat-settings.json — same shape, with a placeholder/empty authKey (NEVER a real dev Auth Key) — and have each developer and CI overwrite it locally/at build time with real credentials. (Enforce "no real key committed" via a pre-commit check or CI, not .gitignore.) For production, CI generates the prod-flavoured file (no Auth Key) at build time (cometchat-flutter-v6-production).

// login AFTER init succeeds. CometChatUIKit.login already checks getLoggedInUser()
// internally and no-ops if that UID is signed in, so no host-side re-login guard is needed.
await CometChatUIKit.login(
  uid,
  onSuccess: (User user) => debugPrint('Logged in: ${user.name}'),
  onError: (CometChatException e) => debugPrint('Login failed: ${e.message}'),
);

Which UID? login() needs a user that ALREADY EXISTS — never invent one. ASK, or take one from Dashboard → Users; fresh apps seed cometchat-uid-1…. The only tentative suggestion is cometchat-uid-1, labelled "if this is a fresh app." Prod → CometChatUIKit.loginWithAuthToken(authToken, …) with a token minted server-side. Init-once, hot-restart, and gating the first frame: references/lifecycle.md.

Widget / API map (BAKED closed list — from the catalog)

Init/session: CometChatUIKit (initFromSettings · login · loginWithAuthToken · logout · loggedInUser), UIKitSettingsBuilder, CometChatSubscriptionType, CometChatException. Core surface: CometChatConversations, CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer; wired affordances CometChatThreadedHeader, CometChatSearch. Grow set (added on request): CometChatUsers, CometChatGroups, CometChatGroupMembers, CometChatChangeScope, CometChatCallLogs. Incoming calls need NO widget — with calling on, the kit presents the overlay itself (-calls).

TWO BARRELS — a real compile trap. package:cometchat_chat_uikit/cometchat_chat_uikit.dart gives you the chat widgets and the re-exported Chat SDK (User, Group, Conversation, BaseMessage, TextMessage — no separate import). Every calls symbol (CometChatIncomingCall, CometChatOutgoingCall, CometChatCallButtons, CometChatCallLogs, CometChatCallBubble, CometChatCalls) lives ONLY in package:cometchat_chat_uikit/cometchat_calls_uikit.dart, and that barrel does NOT re-export the chat widgets — a calls screen imports both. Verified: using CometChatIncomingCall with only the chat import fails to compile. The v6 widget is CometChatThreadedHeader — CometChatThreadHeader (the React name) does NOT exist here. Never carry a name across families.

Hot-path props (BAKED — the golden path needs NO fetch)

• CometChatConversations: onItemTap(Conversation) (select → push the message screen) · hideSearch · searchReadOnly (set true so the field acts as a button) · onSearchTap (→ push CometChatSearch) · conversationsRequestBuilder (scope to user/group when the ask is DM-only or groups-only — reuse the builder, don't client-filter) · hideAppbar · appBarOptions · onBack.
• CometChatMessageHeader: user: / group: (pass the SAME target as the list) · showBackButton (default true) + onBack · hideVoiceCallButton / hideVideoCallButton (call buttons are built in — leave them unless calls are out of scope) · auxiliaryButtonView / trailingView (where a custom action goes — see search below).
• CometChatMessageList: user: / group: · parentMessageId (thread mode) · onThreadRepliesClick [verified] — the type is ThreadRepliesClick = void Function(BaseMessage message, BuildContext context, {CometChatMessageTemplate? template}); a one-argument closure does not compile (DOCS-BACKLOG F2).
• CometChatMessageComposer: user: / group: · parentMessageId (thread mode). A plain send needs nothing else.
• CometChatSearch [verified]: onConversationClicked / onMessageClicked (not the docs' onConversationItemClick / onMessageItemClick — DOCS-BACKLOG F3) · onBack · user: / group: / searchIn to scope it to one chat.

Any OTHER widget or a rarer prop → fetch its .md twin via references/docs-map.md. Full catalog: cometchat-flutter-v6-components.