@cometchat/skills 4.4.1 → 5.0.0

package/contracts.flutter-calls-v5.json

@@ -0,0 +1,77 @@
+{
+  "generatedFrom": "cometchat_calls_sdk 5.0.7 from pub.dev (compiler-verified via flutter analyze probes) + /calls/flutter docs (v5) + calls-core/calls-sdk-flutter source for the @nodoc initFromSettings path and for transcription, which shipped in 5.0.7 with no docs page",
+  "family": "flutter-calls-v5",
+  "major": "v5",
+  "capabilityDetectors": {},
+  "contracts": [
+    {
+      "for": "calls-session-meet",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "init-before-anything",
+        "init-from-settings-default",
+        "settings-file-declared-as-asset",
+        "init-then-login-ordering",
+        "prod-auth-token-guidance",
+        "call-widget-mounted-in-tree",
+        "listener-instance-retained",
+        "listener-registered-before-join",
+        "listener-removed-on-teardown",
+        "leave-session-on-teardown",
+        "no-duplicate-call-controls",
+        "sdk-error-handling",
+        "camera-mic-permissions-declared"
+      ],
+      "docs_topic": "/calls/flutter/join-session",
+      "notes": "HEADLESS meet-style FLOOR for the Flutter Calls SDK v5 skill (cometchat-flutter-v5-sdk). RE-DERIVED against cometchat_calls_sdk 5.0.7, NOT copied from ios-calls-v5. Capability meanings: `init-before-anything` — CometChatCalls.init(callAppSettings, onSuccess:, onError:) must succeed before login/join; CometChatCalls.isInitialized is the guard. `init-from-settings-default` — DEFAULT to CometChatCalls.initFromSettings(onSuccess:, onError:), which persists integrationSource=\"ai-agent\"; CallAppSettingBuilder()..appId=..region= -> .build() -> CometChatCalls.init(...) is the PUBLIC-DOC FALLBACK, and a builder init AFTER initFromSettings re-attributes to \"manual\", so never both. `settings-file-declared-as-asset` — THE FLUTTER FORK: initFromSettings reads cometchat-settings.json through rootBundle, so the file must sit at the project root AND be listed under `flutter: assets:` in pubspec.yaml. iOS needs it in Copy Bundle Resources; web passes settings inline with no file at all. Missing registration fails with the settings-file-not-found error code, not a crash. `call-widget-mounted-in-tree` — THE OTHER FLUTTER FORK: joinSession's onSuccess hands back a `Widget?`, it does not mount anything. Storing it in State and returning it from build() IS the render step; an emit that ignores the argument joins the call invisibly and looks like a broken SDK. `listener-instance-retained` — Flutter listeners are ABSTRACT CLASSES you extend (NOT constructible with named callbacks, whatever the pages show), and remove*Listener takes the SAME instance; an emit that builds a fresh one to remove leaks the first. `no-duplicate-call-controls` — the returned widget already renders mute/video/leave; do NOT stack your own on top (see call-custom-control-panel for the sanctioned path, which hides the built-ins first). `camera-mic-permissions-declared` — AndroidManifest CAMERA/RECORD_AUDIO/MODIFY_AUDIO_SETTINGS and iOS NSCameraUsageDescription/NSMicrophoneUsageDescription, plus a RUNTIME request on Android 6+. FETCH exact signatures from /calls/flutter via references/docs-map.md — bake the map, fetch the manual."
+    },
+    {
+      "for": "calls-oneonone-ringing",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "chat-sdk-init-login",
+        "initiate-call-signaling",
+        "call-listener-registered-with-id",
+        "accept-or-reject-call",
+        "cancel-via-reject-with-status",
+        "join-session-after-accept",
+        "end-call-both-sdks",
+        "call-listener-removed-on-teardown",
+        "sdk-error-handling"
+      ],
+      "docs_topic": "/calls/flutter/ringing",
+      "notes": "1:1 RINGING adds the CHAT SDK (cometchat_sdk v5 (verified against 5.0.6)) on top of the meet floor. `chat-sdk-init-login` — CometChat must be initialised and logged in AS WELL AS CometChatCalls; ringing does not work on the Calls SDK alone. `initiate-call-signaling` — CometChat.initiateCall(Call(receiverID, CometChatReceiverType.user, CometChatCallType.video), onSuccess:, onError:). `call-listener-registered-with-id` — CometChat.addCallListener(listenerID, CallListener(onIncomingCallReceived:, onOutgoingCallAccepted:, onOutgoingCallRejected:, onIncomingCallCancelled:)); note the Flutter CallListener is a MIXIN with default no-op methods: you `with CallListener` on a class and override only what you need. The docs CONSTRUCT it — `CallListener(onIncomingCallReceived: ...)` — which does not compile, because a mixin has no constructor. Same for the Call itself: it takes NAMED required params (receiverUid/receiverType/type), not the positional triple the page shows, and Call.sessionId is nullable. `cancel-via-reject-with-status` — THE FLUTTER/CHAT-SDK TRAP: there is no cancelCall. Cancelling your own outgoing call is rejectCall(sessionId, CometChatCallStatus.cancelled); rejecting someone else's is the same method with CometChatCallStatus.rejected. `end-call-both-sdks` — ending needs BOTH CallSession.getInstance()?.leaveSession() (media) AND CometChat.endCall(sessionId) (signalling + call log); leaving only the session leaves the peer believing the call is live. `call-listener-removed-on-teardown` — CometChat.removeCallListener(listenerID). Ringing cannot be verified with one client: it needs TWO live clients (see references/docs-map.md). The Chat-SDK symbols above are intentionally ABSENT from test-suite/catalogs/flutter-calls-v5.json, which catalogs cometchat_calls_sdk only — validate them against the chat SDK's own catalog, not this one."
+    },
+    {
+      "for": "call-background-handling",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "ongoing-service-launched-on-join",
+        "ongoing-service-aborted-on-teardown",
+        "android-manifest-permissions-stated",
+        "ios-noop-stated"
+      ],
+      "docs_topic": "/calls/flutter/background-handling",
+      "notes": "FLUTTER-ONLY floor — neither ios-calls-v5 nor web-calls-v5 has an analogue. `ongoing-service-launched-on-join` — CometChatOngoingCallService.launch() from the session-joined callback, not from build(); launching before the session exists shows a notification for a call that is not happening. `ongoing-service-aborted-on-teardown` — .abort() alongside leaveSession(), or the notification outlives the call. `android-manifest-permissions-stated` — the foreground-service permissions from the docs page are NOT optional; without them Android kills the call the moment the app backgrounds, which reads to the user as a dropped call rather than a missing manifest entry. `ios-noop-stated` — both methods are safe no-ops on iOS (CallKit owns that state), so the emit may call them unconditionally, but it must SAY that rather than implying it is doing something on iOS."
+    },
+    {
+      "for": "call-voip-push",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "no-single-flutter-push-package-claimed",
+        "android-fcm-path-stated",
+        "ios-apns-callkit-path-stated",
+        "token-registered-with-cometchat",
+        "join-session-on-accept",
+        "dashboard-push-provider-stated",
+        "physical-device-stated"
+      ],
+      "docs_topic": "/calls/flutter/voip-calling",
+      "notes": "Background/killed-app call notifications FLOOR. `no-single-flutter-push-package-claimed` — THE FORK FROM iOS, and the reason this contract exists at all: iOS has a first-party CometChatPushNotifications package that owns PushKit and CallKit, and Flutter DOES NOT. No symbol in test-suite/catalogs/flutter-calls-v5.json implements this feature, so an emit that names a `cometchat_push_notifications` Flutter package is inventing it. `android-fcm-path-stated` / `ios-apns-callkit-path-stated` — the two platforms are wired SEPARATELY (FCM on Android; APNs + PushKit + CallKit, via the app's own plugin choice, on iOS) and the emit must present them as two paths rather than one cross-platform call. `token-registered-with-cometchat` — the device token has to reach CometChat or the push never routes. `join-session-on-accept` — on accept, join the session; the call is already accepted server-side. The last two are STATED prerequisites, not code — a push provider configured in the dashboard, and a PHYSICAL DEVICE, because neither FCM call pushes nor APNs VoIP pushes are delivered to an emulator or Simulator."
+    }
+  ]
+}

package/contracts.flutter-v6.json

@@ -0,0 +1,126 @@
+{
+  "generatedFrom": "cometchat.com/docs — ui-kit/flutter (V6) component pages (conversations, message-list, message-composer, group-members, threaded-messages-header, search) + guide-* task guides, ingested 2026-08-17 (doc-context/flutter-v6/). Adapted from the web-react contracts.json floors per the factory rule (ADD-FRAMEWORK Phase A step 3): same app-level floors, MOBILE platform recipe (Scaffold/SafeArea/flex-fill/keyboard-avoidance + Navigator push routes instead of 100dvh + side panels). Entries noting VERIFY need the exact v6 toggle/prop confirmed from the component's docs page before enforcement.",
+  "family": "mobile-flutter",
+  "major": "v6",
+  "contracts": [
+    {
+      "for": "core-chat-surface",
+      "kind": "feature",
+      "min_capabilities": [
+        "init-login-gate",
+        "conversations-screen",
+        "message-screen-header-list-composer",
+        "threaded-replies-screen-default",
+        "in-chat-message-search-default",
+        "navigation-round-trip",
+        "safe-area-scaffold",
+        "keyboard-avoidance",
+        "no-load-transition-reflow",
+        "affordances-wired-or-hidden",
+        "prod-auth-token-guidance"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/getting-started",
+      "notes": "APP-LEVEL floor for an unscoped 'add chat' on Flutter — the production-ready CORE surface, mobile shape. init-login-gate: CometChatUIKit.init must COMPLETE before login, and login before any widget renders (gate the first screen on both). conversations-screen: CometChatConversations with item tap wired. message-screen-header-list-composer: Navigator.push a messages screen (CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer) carrying the SAME user/group target; back pops to the list (navigation-round-trip — every pushed screen pops back to the state that opened it; the mobile analogue of the web panel-close round-trip). threaded-replies-screen-default (COMPILER-VERIFIED signatures — both docs pages are wrong, see DOCS-BACKLOG): MessageList's onThreadRepliesClick pushes a threaded screen. The callback type is `ThreadRepliesClick = void Function(BaseMessage message, BuildContext context, {CometChatMessageTemplate? template})` — a 1-arg closure does NOT compile. The thread screen is CometChatThreadedHeader(parentMessage:, loggedInUser:) — BOTH required; `message:` is not a parameter — plus a MessageList and MessageComposer that each take parentMessageId AND the SAME user:/group: target as the parent chat (parentMessageId alone is the silent-never-sends trap). Include by default, opt-out only. in-chat-message-search-default: PLATFORM DIFFERENCE (compiler-verified) — unlike React v7, Flutter's CometChatMessageHeader has NO search prop (no showSearchOption/onSearchOptionClicked; 27 params, none search-related). Scoped search still EXISTS: CometChatSearch takes user:/group:/searchIn:. So the in-chat entry point is host-added INTO the header's built-in slot (auxiliaryButtonView or trailingView — the sanctioned 'custom UI goes IN the slot' path), pushing a CometChatSearch screen scoped to the open user/group, with onBack popping. GLOBAL search is different and fully built-in: CometChatConversations exposes hideSearch/searchReadOnly/onSearchTap — set searchReadOnly:true and push CometChatSearch from onSearchTap (the documented pattern). Search result callbacks are onConversationClicked/onMessageClicked (NOT the docs' onConversationItemClick/onMessageItemClick — see DOCS-BACKLOG). safe-area-scaffold + keyboard-avoidance: the surface lives in a Scaffold with SafeArea; the composer stays visible above the keyboard (resizeToAvoidBottomInset / Scaffold default — do NOT wrap in constructs that break it); no-load-transition-reflow: the list fills its screen from frame 1 using the kit's own loading/empty states — never a content-driven container that grows. affordances-wired-or-hidden: any default-on control (search buttons, thread indicator) navigates somewhere real or is hidden — nothing dead-ends. prod-auth-token-guidance: tell the user the Auth Key is dev-only; prod = server-minted auth token + loginWithAuthToken. Mobile is inherently one-screen-at-a-time, so the web responsive-collapse capability is subsumed by navigation-round-trip."
+    },
+    {
+      "for": "chat-experience",
+      "kind": "feature",
+      "min_capabilities": [
+        "tab-scaffold-chats-users-groups-calls",
+        "message-screen-header-list-composer",
+        "group-details-members",
+        "threaded-replies-screen-default",
+        "search-screen",
+        "incoming-call-handling",
+        "navigation-round-trip",
+        "safe-area-scaffold",
+        "keyboard-avoidance",
+        "no-load-transition-reflow",
+        "affordances-wired-or-hidden"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/flutter-tab-based-chat",
+      "notes": "The GROW target — the tab-based app the official guides ship (flutter-tab-based-chat + multi-tab-chat-ui-guide): a bottom-tab (or equivalent) scaffold with Chats (CometChatConversations) / Users (CometChatUsers) / Groups (CometChatGroups) / Calls (CometChatCallLogs) tabs; item tap on any tab pushes the messages screen; group details with CometChatGroupMembers (+ kick/ban/scope per the GroupMembers contract); incoming-call-handling = navigatorKey: CallNavigationContext.navigatorKey set on the root MaterialApp (with calling enabled), so the kit's own CallEventService overlay surfaces an incoming call from ANY screen — the host must NOT add its own CallListener or mount CometChatIncomingCall (that plus the kit's overlay = a DOUBLE incoming screen; cometchat-flutter-v6-calls); every pushed screen pops back cleanly. Emitted only when the user asks for the full app — NOT the default."
+    },
+    {
+      "for": "CometChatConversations",
+      "kind": "component",
+      "min_capabilities": [
+        "conversation-list",
+        "last-message-preview",
+        "unread-count",
+        "delete-conversation",
+        "presence",
+        "receipts",
+        "typing-preview",
+        "infinite-scroll",
+        "realtime-updates",
+        "item-tap-navigation"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/conversations",
+      "notes": "Ships these by default — surface, don't hand-build. item-tap-navigation is HOST work (push the messages screen). Scope the request builder when the ask is 1:1-only or groups-only (ConversationsRequestBuilder conversationType — VERIFY exact v6 prop name); don't client-filter."
+    },
+    {
+      "for": "CometChatMessageList",
+      "kind": "component",
+      "min_capabilities": [
+        "message-bubbles-all-default-types",
+        "receipts",
+        "reactions",
+        "message-actions-menu",
+        "quoted-reply",
+        "thread-indicator-wired-or-hidden",
+        "mark-as-unread",
+        "report-message",
+        "moderation-auto-handling",
+        "infinite-scroll",
+        "realtime-updates"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/message-list",
+      "notes": "Reactions/mentions/quoted-reply/report are integral in v6 — never re-implement. thread-indicator-wired-or-hidden: wire onThreadRepliesClick (see the core-chat-surface note for the exact ThreadRepliesClick signature) to push the thread screen, or hide the affordance — never leave it dead-ending. Moderation rendering is automatic — emit ZERO moderation UI."
+    },
+    {
+      "for": "CometChatMessageComposer",
+      "kind": "component",
+      "min_capabilities": [
+        "text-send",
+        "media-attachments-action-sheet",
+        "voice-recording",
+        "emoji",
+        "mentions",
+        "quoted-reply-preview",
+        "typing-events"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/message-composer",
+      "notes": "All built-in (v6 MessageComposerBloc; inline audio recorder). Quoted-reply preview renders via CometChatMessagePreview. Dashboard-enabled extensions (stickers/polls/collab) appear in the action sheet AUTOMATICALLY — zero registration code (v6 architecture)."
+    },
+    {
+      "for": "CometChatGroupMembers",
+      "kind": "component",
+      "min_capabilities": [
+        "view-members",
+        "kick-member",
+        "ban-member",
+        "change-scope",
+        "search-members",
+        "presence"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/group-members",
+      "notes": "A group-details surface that shows members MUST carry the full moderation minimum (view/kick/ban/scope — scope via CometChatChangeScope), scope-gated to admin/owner. view-banned-members: VERIFY whether v6 ships a banned view; if not, SDK fallback (BannedGroupMembersRequestBuilder + unbanGroupMember, sdk/flutter) — close the ban round-trip like the web AUDIT-082."
+    },
+    {
+      "for": "onboarding-plan",
+      "kind": "feature",
+      "min_capabilities": [
+        "discovery-summary",
+        "feature-coverage-uikit-or-sdk-tagged",
+        "numbered-action-list",
+        "files-that-change",
+        "packages-with-major-pins",
+        "credential-strategy",
+        "modify-or-approve-gate"
+      ],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/flutter/getting-started",
+      "notes": "Same seven-section plan-completeness contract as the pack-wide onboarding (references/plan-artifact.md) — inherited unchanged; listed here so the family's reviewer can gate on it. Flutter discovery signals: pubspec.yaml deps (cometchat_chat_uikit / cometchat_sdk majors), Flutter SDK constraint, state-mgmt (bloc/provider/riverpod/getx), navigation (go_router/Navigator), flavors/env handling (--dart-define / envied / flutter_dotenv), existing .cometchat config."
+    }
+  ]
+}

package/contracts.ios-calls-v5.json

@@ -0,0 +1,67 @@
+{
+  "generatedFrom": "CometChatCallsSDK 5.0.4 (shipped .swiftinterface, arm64-apple-ios) + /calls/ios docs (v5, preview) + calls-core ios-sdk source for the @nodoc initFromSettings path",
+  "family": "ios-calls-v5",
+  "major": "v5",
+  "capabilityDetectors": {},
+  "contracts": [
+    {
+      "for": "calls-session-surface",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "init-before-anything",
+        "init-from-settings-default",
+        "settings-file-bundled",
+        "init-then-login-ordering",
+        "prod-auth-token-guidance",
+        "join-into-sized-uiview-container",
+        "listener-registered-before-join",
+        "listener-removed-on-teardown",
+        "leave-session-on-teardown",
+        "no-duplicate-call-controls",
+        "sdk-error-handling",
+        "camera-mic-usage-descriptions"
+      ],
+      "docs_topic": "/calls/ios/overview",
+      "notes": "HEADLESS meet-style FLOOR for the iOS Calls SDK v5 skill (cometchat-ios-v5-sdk) — the iOS analogue of web's calls-session-surface, RE-DERIVED against CometChatCallsSDK 5.0.4 rather than copied. Capability meanings: `init-before-anything` — CometChatCalls must be initialised before login/join; nothing joins before it succeeds. `init-from-settings-default` — DEFAULT to CometChatCalls.initFromSettings(onSuccess:onError:), which persists integrationSource=\"ai-agent\" (calls-core: SdkIdentification.setIntegrationSource). CallAppSettingsBuilder().setAppId().setRegion().build() -> CometChatCalls(callsAppSettings:) is the PUBLIC-DOC FALLBACK; a direct builder init AFTER initFromSettings re-attributes to \"manual\", so do not do both. `settings-file-bundled` — iOS initFromSettings reads a PHYSICAL cometchat-settings.json from Bundle.main (root appId+region, optional callsSDK{host,adminHost,clientHost,callsHost}); it MUST be in the target's Copy Bundle Resources or init fails SETTINGS_FILE_NOT_FOUND. This is a NATIVE FORK: the web skill passes settings INLINE with no file. `join-into-sized-uiview-container` — joinSession takes a UIView container that must have real bounds; a zero-frame view renders the call invisibly. iOS ships TWO valid join paths and BOTH satisfy this: generateToken(sessionID:) -> joinSession(callToken:callSetting:container:), or joinSession(sessionID:callSetting:container:) directly. `no-duplicate-call-controls` — the default call surface already renders mute/video/leave; do NOT add external buttons (AUDIT-170). Use ButtonClickListener to OBSERVE them instead. `camera-mic-usage-descriptions` — NSCameraUsageDescription + NSMicrophoneUsageDescription in Info.plist, or the call dies on first permission request. FETCH exact signatures from /calls/ios via references/docs-map.md — bake the map, fetch the manual."
+    },
+    {
+      "for": "calls-oneonone-ringing",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "chat-sdk-init-login",
+        "initiate-call-signaling",
+        "call-listener-registered-with-id",
+        "accept-or-reject-call",
+        "join-session-after-accept",
+        "end-call-both-sdks",
+        "call-listener-removed-on-teardown",
+        "sdk-error-handling"
+      ],
+      "docs_topic": "/calls/ios/ringing",
+      "notes": "1:1 RINGING adds the CHAT SDK (CometChatSDK v4) for signalling on top of the meet floor. `chat-sdk-init-login` — CometChat must be initialised and logged in as well as CometChatCalls; ringing does not work on the Calls SDK alone. `initiate-call-signaling` — CometChat.initiateCall(call:onSuccess:onError:) with a Call(receiverId:callType:receiverType:); optional timeout: defaults to 45s. `call-listener-registered-with-id` — CometChat.addCallListener(<uniqueID>, self) + CometChatCallDelegate (onIncomingCallReceived / onOutgoingCallAccepted / onOutgoingCallRejected / onIncomingCallCancelled / onCallEndedMessageReceived). `end-call-both-sdks` — THE iOS-SPECIFIC TRAP: ending a call needs BOTH CallSession.shared.leaveSession() (media) AND CometChat.endCall(sessionID:) (signalling). Leaving only the session leaves the peer believing the call is live and the call log incomplete. `call-listener-removed-on-teardown` — CometChat.removeCallListener(<uniqueID>). Ringing cannot be verified with one client: it needs TWO live clients (see references/docs-map.md). The Chat-SDK symbols above are intentionally ABSENT from catalogs/ios-calls-v5.json, which catalogs CometChatCallsSDK only — validate them against the chat SDK's own catalog, not this one."
+    },
+    {
+      "for": "calls-voip-push",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "push-sdk-separate-package",
+        "import-module-not-class",
+        "initialize-after-chat-init",
+        "delegate-assigned",
+        "device-token-forwarded",
+        "registration-failure-surfaced",
+        "present-call-screen-handled",
+        "call-cleanup-handled",
+        "notify-calls-sdk-ready",
+        "no-hand-rolled-pushkit-or-callkit",
+        "apns-voip-provider-stated",
+        "physical-device-stated"
+      ],
+      "docs_topic": "/notifications/ios-push-notifications-sdk",
+      "notes": "VoIP call notifications FLOOR. Capability meanings: `push-sdk-separate-package` — this is CometChatPushNotifications 1.0.0, NOT CometChatCallsSDK; `import-module-not-class` — the import is CometChatPushNotificationsSwift (module_name), while the class is CometChatPushNotifications, and importing the class name does not compile; `initialize-after-chat-init` — initialize(config:) runs after CometChat.init; `device-token-forwarded` — registerDeviceToken(_:) called from didRegisterForRemoteNotificationsWithDeviceToken; `present-call-screen-handled` — the call is ALREADY accepted server-side when presentCallScreen fires, so present and join, never accept again; `notify-calls-sdk-ready` — without it a cold-start VoIP push never reaches presentCallScreen; `no-hand-rolled-pushkit-or-callkit` — the SDK owns PKPushRegistryDelegate and CXProviderDelegate, and writing either fights it for the same callbacks; the last two are STATED prerequisites, not code — an APNs VoIP provider in the dashboard, and a physical device, because VoIP pushes are never delivered to the Simulator."
+    }
+  ]
+}