docs(flutter calls): fix the Calls SDK API errors across /calls/flutter — including listeners that cannot be constructed

[anshuman-cometchat]

Two passes over /calls/flutter, both verified against the shipped cometchat_calls_sdk 5.0.6.
Sibling to the Flutter headless Calls SDK skill, cometchat-team/cometchat-skills#184 — the same
way #489 paired with cometchat-team/cometchat-skills#183.

---

Pass 1 — the Tier-2 Dart gate: 56 errors across 25 pages → 3

The one that matters most

The documented token flow is deprecated and mis-typed — and it is the invariant the whole
calling flow hangs off (init → login → token → joinSession).

• CometChatCalls.generateToken is @Deprecated in 5.0.6: "use generateCallToken; auth
  token is now managed internally after login()"
• it takes two positional arguments, not a named sessionId:
• its callback yields GenerateToken — while the pages typed it for CallToken, which
  belongs to the replacement

So the pages were a hybrid: the deprecated method name with the new method's callback type. And
no page mentioned generateCallToken at all — the current token API was undocumented, and the
documented one could not run.

The rest

	What	Scope
D1	CometChatCalls.SessionSettingsBuilder() — a top-level class, not a member	23 occurrences, 13 pages
D3	Five listener types are plural in the SDK	34 occurrences, 16 pages
D4	remove*Listener takes the listener object; pages called them with no argument and built the listener inline, so there was nothing to pass	5 sites
D5	CallLog.sessionId, not sessionID	2
D6	CometChatConstants does not exist — the constants are CometChatReceiverType, CometChatCallType, CometChatCallStatus in the Chat SDK	1 page
D7	login / loginWithAuthToken hand back a nullable User, dereferenced unguarded	3

---

Pass 2 — what the gate could not see

Pass 1 renamed the five listener types. It did not fix their shape, and the shape is the part
that does not compile. This came out of building a Flutter harness from these pages and running
flutter analyze over it (skills#184).

All five listener types are abstract classes

SessionStatusListeners, ParticipantEventListeners, MediaEventListeners,
ButtonClickListeners and LayoutListeners are abstract class in 5.0.6. Every page builds them
with named callbacks — SessionStatusListeners(onSessionJoined: () { … }) — which the analyzer
rejects with instantiate_abstract_class. 34 sites across 16 pages.

Each is now a class that extends the type and overrides only the callbacks with a real body.
Empty stubs are dropped — the abstract class already gives every member a no-op body, so
onAudioMuted: () {} was pure noise — and a one-line comment names what was removed so the
example still shows what else exists.

The singular spellings in prose are fixed too (11 pages). Pass 1 only touched fences, so a
reader following a parameter table still typed an undefined type.

addLayoutListener / removeLayoutListener do not exist

CallSession exposes set layoutListener(LayoutListeners?) and its getter. Not an add/remove
pair — one slot, cleared by assigning null. 4 sites. This matters beyond the compile error:
only a single layout listener can ever be registered, and the add/remove spelling actively hid that.

Ringing — three Chat-SDK shapes

The page wrote	Reality
Call(receiverID, receiverType, callType)	Call has no positional parameters — required named receiverUid / receiverType / type
CallListener(onIncomingCallReceived: …)	CallListener is a mixin — no constructor. Now class _AppCallListener with CallListener
joinCallSession(call.sessionId!)	Call.sessionId is nullable — the force-unwrap turns a handled error into a crash

CometChat.initiateCall has no timeout parameter

The page documented it in two tables and a code sample with a "defaults to 45 seconds" story. The
signature is (Call, {onSuccess, onError}), and the repository beneath it takes only
receiver/receiverType/type — there is no client-side timeout at any layer. The section now
says what is true: the timeout is server-side, and to end an unanswered call earlier you cancel it
yourself with rejectCall(sessionId, CometChatCallStatus.cancelled) on your own timer.

User is exported by BOTH barrels

Ringing needs cometchat_calls_sdk and cometchat_sdk, and each declares a User, so the
file fails ambiguous_import until one side hides it. No page said so; the ringing page now does,
with the hide User import.

---

Deliberately NOT changed

The eight CometChatCalls.muteAudio / switchCamera / setAudioMode / PiP calls on
migration-guide-v5 sit inside its "v4" tab, showing the old API on purpose — the same shape
as upgrading-from-v5 on the UI Kit side. That page needs the gate's --exclude, not an edit. I
was one command from "fixing" correct content before checking the surrounding tab.

Verification, and what it does not cover

typecheck-fences-dart against the pinned 5.0.6, all 25 pages: 10 errors, every one accounted
for — 8 are that v4 tab, 2 are the User clash, which is a shared-fence-project artifact and
a real trap, so it is documented rather than edited away. Zero unexplained.

Stated rather than hidden: 12 fences on these pages parse in no shape and are never checked.
Both D3 and the abstract-listener defect were hiding in exactly that blind spot — the second one
was found by a compiler pointed at a harness, not by this gate. Treat the residual number as a
floor, not a total.

[raj-dubey1]

Docs review — Flutter Calls SDK v5 API corrections

Verdict: request changes (a P0 was introduced by the edit; the API renames themselves are correct, verified against cometchat_calls_sdk@5.0.7 + cometchat_sdk@5.0.7).

🔴 P0 — the edit broke the very snippets it set out to fix (must fix)

Wherever a listener lived inside a _setupX() method, unwrapping the closure left a stray ); and turned the assignment into a statement ending in , → non-compiling Dart. 12 occurrences across 5 files (each appears in both the step snippet and its "Complete Example"):

_sessionListener = _SessionStatusListener(),   // ← trailing comma, should be ;
);                                             // ← orphaned close-paren = syntax error

• calls/flutter/background-handling.mdx:113-114 (+ ~204, ~222)
• calls/flutter/custom-control-panel.mdx:234-235, 260-261 (+ ~356, ~362)
• calls/flutter/custom-participant-list.mdx:232-233 (+ ~375)
• calls/flutter/in-call-chat.mdx:125-126 (+ ~326)
• calls/flutter/share-invite.mdx:60-61 (+ ~271)

Correct form:

_sessionListener = _SessionStatusListener();
CallSession.getInstance()?.addSessionStatusListener(_sessionListener);

(The top-level, non-_setup conversions in events / audio-modes / call-layouts / idle-timeout / pip / raise-hand / recording / screen-sharing / participant-management are clean.)

🟡 P1 — base branch: this fix won't reach production on its own

PR targets docs/skills-v5-temp, which is diverged from main (ahead 75 / behind 43). calls/flutter/** already exists on main with these same errors, so prod needs the fix — but merging here only lands it on the temp branch; it reaches prod solely via the still-open umbrella PR #482 (skills-v5-temp → main). Please confirm that path actually ships this.

🟡 P2 — pre-existing, worth fixing while here

Several pages build settings with a cascade but never call .build(), passing a SessionSettingsBuilder where joinSession wants the built SessionSettings (custom-control-panel, custom-participant-list, in-call-chat, share-invite, voip-calling, background-handling).

✅ Verified correct against 5.0.7 source

Pluralized listeners (SessionStatusListeners/MediaEventListeners/LayoutListeners/ParticipantEventListeners/ButtonClickListeners, abstract with no-op defaults) · removeXListener(instance) · layoutListener setter/getter (the "listener that can't be constructed" fix) · generateToken→generateCallToken(sessionId, …) · login onSuccess User? · SessionSettingsBuilder() as top-level (not a CometChatCalls. static) · sessionID→sessionId · ringing Call(receiverUid:, receiverType:, type:) + CometChatReceiverType/CallType/CallStatus (old CometChatConstants.* doesn't exist in v5) · initiateCall has no timeout · CallListener mixin · callInitiator as User? cast · import … hide User collision note.

Build safety: all 20 files MODIFIED (no renames/removes/adds) → 0 nav breaks, 0 redirect need, 0 orphans.

---

Automated docs-PR review (Claude Code). Verified against the published pub.dev packages, not from memory.

[anshuman-cometchat]

Thanks — this was a genuinely useful review. All three points addressed; one of them I'd have got wrong without it.

🔴 P0 — already fixed, in 5c7a8bf

Same diagnosis, same 12 sites, same 5 files. The review lands just after the repair commit, so it reads as outstanding but isn't — re-checked on the current head and there are 0 occurrences of the pattern.

Worth saying plainly: that corruption was mine. The listener rewrite replaced X = SessionStatusListeners( … ); and left the original call's trailing ); behind. It surfaced as "12 fences parsed in NO shape" in the Dart gate, and I initially read that as a pre-existing blind spot rather than damage I'd just done. Your independent confirmation of the exact same site list is a good check on that.

🟡 P1 — you're right, and I nearly concluded the opposite

My first check said calls/flutter/** doesn't exist on main. That was wrong: it was a query against a local ref that didn't exist, and empty output looked like evidence. Re-queried through the API:

• calls/flutter/ on main: 27 files
• call-logs.mdx: 6 nested CallLogRequest.CallLogRequestBuilder occurrences
• events.mdx: 15 constructed listeners
• overview.mdx: API Level 24 and Minimum iOS 12 — both too low

So prod does carry these, and this PR reaches it only via #482 (docs/skills-v5-temp → main), which is open. Flagging that as a real dependency rather than claiming it's handled — I can't confirm #482's timeline.

Related, same shape, different tree: #500 corrects ui-kit/flutter/getting-started and call-features, which state minSdk = 24 / iOS 13.0 and 12.0. cometchat_chat_uikit depends on cometchat_calls_sdk unconditionally, so its minSdk 26 / iOS 15.1 bind every UI Kit app whether or not it uses calling — verified by resolving a pubspec whose only dependency is the UI Kit.

🟡 P2 — real, fixed in e048c10: 12 sites, 6 pages

A cascade returns the receiver, so final s = SessionSettingsBuilder()..setTitle(x); binds the builder to s. Two failure modes: a snippet that stops there teaches readers to pass a builder to joinSession (a type error they hit, not the page), and a call site that rescues it with s.build() reads as though s were already settings. Now the idiom used everywhere else on the tree:

final sessionSettings = (SessionSettingsBuilder()
    ..hideControlPanel(true))
    .build();

The gate is structurally blind to this class, which is worth recording: an unconsumed builder produces no type error, so "0 kit-API errors across 48 fences" was true and did not mean correct. Same blind spot as the unparseable fences in a different shape — it took a human reader to find it.

Two things from the merge

transcription.mdx was an add/add — and yours got there first. Someone documented Flutter transcription while this branch was open. That page is 342 lines to my 188 and covers everything mine did, including both facts I thought I was contributing (start/stop throw rather than reporting via callback; both buttons default to hidden), plus built-in UI controls, caption settings and a complete example. Took theirs and dropped mine — a second, thinner page would have been worse than useless.

One defect rode in with the merge. Both the new "Access Transcripts" section and the adopted transcription page build call logs with CallLogRequest.CallLogRequestBuilder().setLimit(30) — the exact nested-prefix + setX() form this PR removes elsewhere. Fixed in both. On the call-logs table I kept the verified field list and folded in your hasTranscriptions row, noting it's the one member of that builder that also has a setter (setHasTranscriptions, added for parity with the other SDKs). CallLog.getTranscriptions() and the transcriptions field both verified real in 5.0.7.

State

Conflicts resolved; MERGEABLE / CLEAN. Gate on the whole /calls/flutter tree against the pinned cometchat_calls_sdk 5.0.7: 51 fences analyzed, 0 unparseable, 0 kit-API errors.

The zero-unparseable is new since your review and is the part I'd weight most — the tree previously had 12 fences the gate silently skipped, and the two largest defects it eventually found (a phantom CometChatMessages, and every CometChat.getGroup/joinGroup/createGroup call being wrong) were hiding in exactly those.