@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-flutter-v5-sdk/references/platform-notes.md

@@ -0,0 +1,48 @@
+# Platform notes — Flutter Calls SDK v5
+
+Two surfaces that sit beside the call rather than on the join path: keeping a call alive when the
+app goes to the background, and ringing a user whose app is closed. Neither is needed to get a
+call working; both are needed before shipping one.
+
+## Backgrounding (FLUTTER-ONLY — `CometChatOngoingCallService`)
+Android kills a call the moment the app backgrounds unless a foreground service holds it:
+`CometChatOngoingCallService.launch()` from the **session-joined** callback (not `build()`), `.abort()`
+alongside `leaveSession()`. Both are **safe no-ops on iOS**, where CallKit owns that state — call them
+unconditionally, but say that rather than implying they do something on iOS. The manifest permissions
+on `/calls/flutter/background-handling` are **not optional**; without them the call drops on background
+and reads as a network fault. No iOS or web analogue exists.
+
+## Call notifications when the app is backgrounded or killed (NO single Flutter package)
+**iOS has a first-party `CometChatPushNotifications` package that owns PushKit and CallKit. Flutter
+does not.** There is no `cometchat_push_notifications` on pub.dev, and **no symbol in this skill's
+catalog implements this feature** — if an emit names such a package it invented it. The real shape is
+two separate paths over the app's own push plugin:
+- **Android** — FCM: register the token with CometChat, receive the call payload, show the incoming UI.
+- **iOS** — APNs + PushKit + CallKit, wired by the app (`flutter_callkit_incoming` or equivalent), not by CometChat.
+- On accept, **join the session — the call is already accepted server-side**; do not accept again.
+- **Prerequisites (state them, they are not code):** a push provider configured in the dashboard, and a **PHYSICAL DEVICE** — neither FCM call pushes nor APNs VoIP pushes reach an emulator or Simulator.
+Pages: `/calls/flutter/voip-calling`, `/notifications/flutter-push-notifications-android`, `/notifications/flutter-push-notifications-ios`.
+
+## iOS Simulator on Apple Silicon — `CometChatWebRTC` excludes arm64
+
+`CometChatWebRTC.podspec` sets `EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64`, and CocoaPods
+propagates it into `Pods-Runner`. So the app builds **x86_64** and Flutter warns:
+
+> The following target(s) do not support arm64 architecture, which is a requirement for Apple
+> Silicon iOS 26+ simulators: CometChatWebRTC (transitive dependency of Flutter plugin
+> cometchat_calls_sdk)
+
+What that means in practice:
+
+- **iOS 18 simulator: works**, through Rosetta. Verified — a calling app built, launched, logged
+  in and joined a live session.
+- **iOS 26+ simulator: will not run at all.**
+- **Physical device: unaffected** (the `ios-arm64` slice is fine).
+
+The vendored `WebRTC.xcframework` **does** ship `ios-arm64_x86_64-simulator`, so the exclusion
+looks gratuitous rather than necessary — but it is the SDK's podspec, not something the app can
+override cleanly. Target a device or an iOS 18 simulator, and do not spend time hunting a missing
+slice that is present.
+
+Nothing in `/calls/flutter/**` mentions this, troubleshooting included. It is the most likely
+first-five-minutes blocker for an iOS developer.

package/skills/cometchat-flutter-v5-sdk/references/transcription.md

@@ -0,0 +1,87 @@
+# Transcription & closed captions — Flutter Calls SDK 5.0.7
+
+> Transcription shipped in `cometchat_calls_sdk` **5.0.7** (published 2026-09-02). It had no
+> documentation at all when this file was written; **`/calls/flutter/transcription` now exists**
+> (docs#492, DOCS-BACKLOG D3) and is the source of truth once it merges. Until then this file is
+> a labelled **STOPGAP** — every shape below is compile-verified against the published package,
+> and both were written from the same verification pass, so they agree. Prefer the page when it
+> lands, and delete the stopgap note here.
+
+Server-side feature: **state the dashboard prerequisite** rather than assuming it is enabled.
+
+## Control — on `CallSession.getInstance()`
+
+```dart
+await CallSession.getInstance()?.startTranscription();
+await CallSession.getInstance()?.stopTranscription();
+final bool? on = CallSession.getInstance()?.isTranscribing;
+```
+
+## Session settings — ⚠️ both buttons are HIDDEN BY DEFAULT
+
+```dart
+final settings = (SessionSettingsBuilder()
+      ..setType(SessionType.video)
+      ..enableAutoStartTranscription(true)   // start with the session
+      ..hideTranscriptionButton(false)       // ← REQUIRED to show it
+      ..hideClosedCaptionButton(false)       // ← REQUIRED to show it
+      ..setCaptionLanguage('en-US'))         // a METHOD, not a field
+    .build();
+```
+
+`hideTranscriptionButton` and `hideClosedCaptionButton` both default to **`true`**, joining
+`hideRecordingButton`, `hideShareInviteButton` and `hideChatButton`. Wiring a click handler
+without passing `false` gives you a control that can never appear — the same trap, now on five
+buttons rather than three.
+
+Note `setCaptionLanguage(String)` is a **setter method**, unlike `CallAppSettingBuilder`'s
+`..appId =` fields. This builder is method-cascade throughout; only the *call-log* builder takes
+field assignments.
+
+## Retrieval
+
+```dart
+final req = (TranscriptRequestBuilder()
+      ..setSessionId(sessionId)
+      ..setLimit(30))          // defaultLimit 30 · maxLimit 1000
+    .build();
+
+await req.fetchNext(
+  onSuccess: (List<Transcript> transcripts) { /* ... */ },
+  onError: (CometChatCallsException e) { /* ... */ },
+);
+await req.fetchPrevious(onSuccess: (_) {}, onError: (_) {});
+```
+
+The callbacks are **required** — the same shape as `CallLogRequest.fetchNext`. Both methods also
+return the `Future<List<Transcript>>`, so either channel works, but you cannot omit the callbacks.
+
+### `Transcript`
+
+| Field | Type | |
+|---|---|---|
+| `tid` | `String?` | transcript id |
+| `mid` | `String?` | message id |
+| `roomName` | `String?` | the session's room |
+| `startTime` / `endTime` | `int?` | epoch bounds |
+| `url` · `transcriptUrl` | `String?` | where to fetch the text |
+| `transcriptDate` | `String?` | |
+| `metaData` | `Map<String, dynamic>?` | the raw server record — new/unknown keys are never lost |
+
+All nullable — unwrap before use. (Nine fields total; `metaData` is barrel-reachable and on the live `/calls/flutter/transcription` page too.)
+
+## Finding calls that have one
+
+```dart
+final logs = (CallLogRequestBuilder()..hasTranscriptions = true).build();
+```
+
+`CallLogRequestBuilder` also gained a `setHasTranscriptions(bool)` **method** in 5.0.7 — the only
+setter on an otherwise all-field builder. Prefer the field assignment for consistency with the
+rest of that builder.
+
+## What Flutter still does not have
+
+No `TranscriptsBuilder`-style server filter beyond session id and limit, and no live caption
+*stream* to subscribe to — captions are rendered by the SDK's own UI, and transcripts are fetched
+after the fact. iOS's `TranscriptsRequest` surface is not identical; do not port its snippets.