@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-angular-calls/references/add-calls-to-existing-chat.md

@@ -34,7 +34,8 @@ In your auth service, after `CometChat.login`:
 ```ts
 const user = await CometChat.login(uid, env.AUTH_KEY);
 const authToken = user.getAuthToken();
-await CometChatCalls.login(authToken);
+// CometChatCalls.login(uid, authKey?) takes a UID; to authenticate with a token use loginWithAuthToken:
+await CometChatCalls.loginWithAuthToken(authToken);
 ```
 
 ---
@@ -81,7 +82,7 @@ export class CallEventsService {
 
 - [ ] `@cometchat/calls-sdk-javascript@^5` in package.json
 - [ ] Calls SDK init runs after chat SDK init in `AppInitService`
-- [ ] `CometChatCalls.login(authToken)` after `CometChat.login`
+- [ ] `CometChatCalls.loginWithAuthToken(authToken)` after `CometChat.login` (NOT `CometChatCalls.login`, which expects a UID)
 - [ ] `<cometchat-incoming-call>` rendered at app root (sibling of `router-outlet`)
 - [ ] All custom `addEventListener` callbacks wrapped in `NgZone.run`
 - [ ] Run `cometchat verify --calls` — should pass

package/skills/cometchat-angular-calls/references/call-layouts.md

@@ -10,26 +10,33 @@ Same SDK API as web. Angular wraps layout state in a service so multiple compone
 ## Layout service
 
 ```ts
-import { Injectable, NgZone } from "@angular/core";
+import { Injectable, NgZone, OnDestroy } from "@angular/core";
 import { BehaviorSubject } from "rxjs";
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
 export type CallLayout = "TILE" | "SIDEBAR" | "SPOTLIGHT";
 
 @Injectable({ providedIn: "root" })
-export class CallLayoutService {
+export class CallLayoutService implements OnDestroy {
   readonly layout$ = new BehaviorSubject<CallLayout>("TILE");
 
+  // addEventListener returns an unsubscribe fn — there is NO CometChatCalls.removeEventListener.
+  private off: () => void;
+
   constructor(private zone: NgZone) {
-    CometChatCalls.addEventListener("onCallLayoutChanged", (next: string) => {
+    this.off = CometChatCalls.addEventListener("onCallLayoutChanged", (next: string) => {
       this.zone.run(() => this.layout$.next(next as CallLayout));
     });
   }
 
   set(layout: CallLayout): void {
-    CometChatCalls.setLayout(layout);
+    CometChatCalls.setLayout(layout);   // static runtime layout switch — valid
     this.layout$.next(layout);
   }
+
+  ngOnDestroy(): void {
+    this.off();
+  }
 }
 ```
 
@@ -65,17 +72,26 @@ export class LayoutSwitcherComponent {
 
 ---
 
-## Pass initial via call settings
+## Pass initial via session settings
+
+`joinSession` takes a **`SessionSettings` object**, not a builder result. The initial layout and
+the change-layout button visibility are plain object fields (`layout`, `hideChangeLayoutButton`).
+The builder has NO `setLayout` (its layout setter is the deprecated `setMode`) and NO
+`setHideChangeLayoutButton`, and its output (`CallSettings`) is not accepted by `joinSession`.
 
 ```ts
-const callSettings = new CallSettingsBuilder()
-  .setLayout("SPOTLIGHT")
-  .setHideChangeLayoutButton(true)  // if you ship LayoutSwitcherComponent
-  .build();
+const sessionSettings = {
+  sessionType: "VIDEO",
+  layout: "SPOTLIGHT",
+  hideChangeLayoutButton: true,   // if you ship LayoutSwitcherComponent
+} as const;
 
-await CometChatCalls.joinSession(callToken, callSettings, container.nativeElement);
+await CometChatCalls.joinSession(callToken, sessionSettings, container.nativeElement);
 ```
 
+To switch layout at runtime use the static `CometChatCalls.setLayout(layout)` (as the
+`CallLayoutService.set` above does).
+
 ---
 
 ## Anti-patterns
@@ -92,8 +108,9 @@ Web sister rules apply, plus Angular-specific:
 
 - [ ] `CallLayoutService` provided in root
 - [ ] `NgZone.run` wraps the SDK callback
-- [ ] `mat-button-toggle-group` `(change)` calls `svc.set`
-- [ ] Initial layout via `CallSettingsBuilder.setLayout`
+- [ ] `mat-button-toggle-group` `(change)` calls `svc.set` (which calls static `CometChatCalls.setLayout`)
+- [ ] Initial layout via the `SessionSettings` object `{ layout, hideChangeLayoutButton }` passed to `joinSession` (no `CallSettingsBuilder`)
+- [ ] Listener unsubscribe fn captured + called in `ngOnDestroy` (no `removeEventListener`)
 - [ ] Browser smoke: 3 tabs, each picks a different layout, no cross-talk
 
 ---

package/skills/cometchat-angular-calls/references/call-session.md

@@ -1,6 +1,6 @@
 # Call session — joinSession with no ringing (Angular)
 
-Same SDK API as web. This file mirrors the upstream Angular sample at `~/Downloads/calls-sdk/calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-angular/src/app/pages/join-session/`. Customer-validated against the v5 SDK as the known-good shape.
+Same SDK API as web. This file mirrors the upstream Angular sample at `calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-angular/src/app/pages/join-session/`. Customer-validated against the v5 SDK as the known-good shape.
 
 **Read first:** `cometchat-react-calls/references/call-session.md` — full architecture (sessionId strategies, server-side authorization, token generation), then come back here for Angular specialization.
 
@@ -163,5 +163,5 @@ Read `sessionId` via `ActivatedRoute.snapshot.paramMap.get('sessionId')` in `ngO
 - `cometchat-react-calls/references/call-session.md` — full architecture (sessionId strategies, server-side authorization)
 - `cometchat-angular-calls/SKILL.md` — Angular-specific dual-SDK init pattern
 - `references/ngzone-and-async-callbacks.md` — why NgZone.run matters for SDK events
-- Upstream Angular sample — `~/Downloads/calls-sdk/calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-angular/src/app/pages/join-session/`
+- Upstream Angular sample — `calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-angular/src/app/pages/join-session/`
 - Canonical docs: https://www.cometchat.com/docs/calls/javascript/join-session

package/skills/cometchat-angular-calls/references/custom-ui.md

@@ -7,7 +7,7 @@ Same architecture as React + RN custom UI; Angular-specific because of NgZone, C
 ## Two paths
 
 1. **Style the kit's selectors** — pass Angular `[input]` props + content projection (`<ng-content select="...">`). Cheapest.
-2. **Build your own component on the SDK** — direct `CometChatCalls.joinSession(token, settings, container)` with your own `<video>` elements wrapped in Angular components. (`startSession` is a deprecated v4 shim — use `joinSession`.)
+2. **Build your own component on the SDK** with your own `<video>` elements wrapped in Angular components. ⚠️ Two join APIs by settings type: **hybrid (hide-chrome)** → `SessionSettings` object + `joinSession`; **fully-custom (`enableDefaultLayout(false)`, own tiles)** → `CallSettingsBuilder` + the deprecated `startSession` (joinSession does NOT accept builder output). This reference shows the fully-custom path.
 
 This reference covers path 2.
 
@@ -54,6 +54,8 @@ export class OngoingCallComponent implements OnInit, OnDestroy {
   constructor(private zone: NgZone) {}
 
   async ngOnInit() {
+    // ⚠️ CometChatCalls.OngoingCallListener is @deprecated (use addEventListener).
+    // It's only here because enableDefaultLayout(false) + startSession require it.
     this.listener = new CometChatCalls.OngoingCallListener({
       onUserListUpdated: (users: unknown) => {
         this.zone.run(() => { /* update roster */ });
@@ -67,18 +69,23 @@ export class OngoingCallComponent implements OnInit, OnDestroy {
       },
     });
 
+    // CallSettingsBuilder method names (verified vs calls-sdk-javascript@5):
+    //   - NO .setSessionID() on the builder — sessionId flows via generateToken()
+    //   - .setIsAudioOnlyCall(bool), not .setIsAudioOnly()
+    //   - .setCallListener(listener), not .setCallEventListener()
     const settings = new CometChatCalls.CallSettingsBuilder()
-      .setSessionID(this.sessionId)
-      .setIsAudioOnly(false)
+      .setIsAudioOnlyCall(false)
       .enableDefaultLayout(false)
-      .setCallEventListener(this.listener)
+      .setCallListener(this.listener)
       .build();
 
-    // v5 — generateToken takes ONLY sessionId. Auth is internal after CometChatCalls.login().
+    // generateToken takes ONLY sessionId. Auth is internal after CometChatCalls.login().
     const tokenRes = await CometChatCalls.generateToken(this.sessionId);
-    // htmlElement is required — pass the call container ref.
-    // joinSession is the v5 canonical — startSession is a deprecated shim.
-    CometChatCalls.joinSession(tokenRes.token, settings, this.callContainerRef.nativeElement);
+    // This fully-custom path uses enableDefaultLayout(false), which builds a CallSettings —
+    // consumed ONLY by the deprecated startSession. joinSession takes a SessionSettings
+    // OBJECT and will NOT accept CallSettingsBuilder output. startSession is the one place
+    // the deprecated call is still required (enableDefaultLayout is builder-only).
+    CometChatCalls.startSession(tokenRes.token, settings, this.callContainerRef.nativeElement);
   }
 
   ngOnDestroy() {
@@ -87,12 +94,13 @@ export class OngoingCallComponent implements OnInit, OnDestroy {
 
   onToggleMute() {
     this.muted = !this.muted;
-    CometChatCalls.muteAudio(this.muted);
+    // No-arg methods — muteAudio(bool) ignores the arg. Use the explicit pair.
+    this.muted ? CometChatCalls.muteAudio() : CometChatCalls.unmuteAudio();
   }
 
   onToggleCamera() {
     this.cameraOff = !this.cameraOff;
-    CometChatCalls.pauseVideo(this.cameraOff);
+    this.cameraOff ? CometChatCalls.pauseVideo() : CometChatCalls.resumeVideo();
   }
 
   onSwitchCamera() {

package/skills/cometchat-angular-calls/references/device-management.md

@@ -10,22 +10,34 @@ Same JS SDK as web. Angular wraps device-list state in a service with RxJS obser
 ## Service-driven device lists
 
 ```ts
-import { Injectable, NgZone } from "@angular/core";
+import { Injectable, NgZone, OnDestroy } from "@angular/core";
 import { BehaviorSubject } from "rxjs";
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-interface MediaDevice { id: string; label: string; }
+// SDK returns standard DOM MediaDeviceInfo objects — use `.deviceId`, NOT `.id`.
 
 @Injectable({ providedIn: "root" })
-export class CallDevicesService {
-  readonly mics$ = new BehaviorSubject<MediaDevice[]>([]);
-  readonly cameras$ = new BehaviorSubject<MediaDevice[]>([]);
-  readonly speakers$ = new BehaviorSubject<MediaDevice[]>([]);
+export class CallDevicesService implements OnDestroy {
+  readonly mics$ = new BehaviorSubject<MediaDeviceInfo[]>([]);
+  readonly cameras$ = new BehaviorSubject<MediaDeviceInfo[]>([]);
+  readonly speakers$ = new BehaviorSubject<MediaDeviceInfo[]>([]);
+
+  // addEventListener returns an unsubscribe fn — there is NO CometChatCalls.removeEventListener.
+  private offs: Array<() => void> = [];
 
   constructor(private zone: NgZone) {
-    CometChatCalls.addEventListener("onAudioModesUpdated", () => {
-      this.zone.run(() => this.refresh());
-    });
+    // Valid device-change event keys (plural = full updated list):
+    this.offs.push(
+      CometChatCalls.addEventListener("onAudioInputDevicesChanged", () => {
+        this.zone.run(() => this.refresh());
+      }),
+      CometChatCalls.addEventListener("onAudioOutputDevicesChanged", () => {
+        this.zone.run(() => this.refresh());
+      }),
+      CometChatCalls.addEventListener("onVideoInputDevicesChanged", () => {
+        this.zone.run(() => this.refresh());
+      }),
+    );
   }
 
   async ensurePermission(): Promise<void> {
@@ -37,25 +49,27 @@ export class CallDevicesService {
     }
   }
 
-  async refresh(): Promise<void> {
-    const [mics, cameras, speakers] = await Promise.all([
-      CometChatCalls.getAudioInputDevices(),
-      CometChatCalls.getVideoInputDevices(),
-      CometChatCalls.getAudioOutputDevices(),
-    ]);
-    this.mics$.next(mics);
-    this.cameras$.next(cameras);
-    this.speakers$.next(speakers);
+  // Device getters are SYNCHRONOUS — they return arrays, not Promises. No await / Promise.all.
+  refresh(): void {
+    this.mics$.next(CometChatCalls.getAudioInputDevices());
+    this.cameras$.next(CometChatCalls.getVideoInputDevices());
+    this.speakers$.next(CometChatCalls.getAudioOutputDevices());
   }
 
-  async selectMic(id: string): Promise<void> {
-    await CometChatCalls.setAudioInputDevice(id);
+  // Setters are SYNCHRONOUS void — no await. They take the deviceId string.
+  selectMic(deviceId: string): void {
+    CometChatCalls.setAudioInputDevice(deviceId);
+  }
+  selectCamera(deviceId: string): void {
+    CometChatCalls.setVideoInputDevice(deviceId);
   }
-  async selectCamera(id: string): Promise<void> {
-    await CometChatCalls.setVideoInputDevice(id);
+  selectSpeaker(deviceId: string): void {
+    CometChatCalls.setAudioOutputDevice(deviceId);
   }
-  async selectSpeaker(id: string): Promise<void> {
-    await CometChatCalls.setAudioOutputDevice(id);
+
+  ngOnDestroy(): void {
+    this.offs.forEach(off => off());   // call the captured unsubscribe fns
+    this.offs = [];
   }
 }
 ```
@@ -71,8 +85,8 @@ export class CallDevicesService {
     <form (ngSubmit)="confirm()">
       <label>Microphone
         <select [(ngModel)]="selectedMic" name="mic">
-          <option *ngFor="let d of mics$ | async" [value]="d.id">
-            {{ d.label || ('Mic ' + d.id.substring(0, 6)) }}
+          <option *ngFor="let d of mics$ | async" [value]="d.deviceId">
+            {{ d.label || ('Mic ' + d.deviceId.substring(0, 6)) }}
           </option>
         </select>
       </label>
@@ -92,14 +106,14 @@ export class DevicePickerComponent implements OnInit {
   constructor(private devices: CallDevicesService) {}
 
   async ngOnInit() {
-    await this.devices.ensurePermission();
-    await this.devices.refresh();
+    await this.devices.ensurePermission();   // getUserMedia IS async
+    this.devices.refresh();                  // device list reads are sync
   }
 
-  async confirm() {
-    if (this.selectedMic) await this.devices.selectMic(this.selectedMic);
-    if (this.selectedCamera) await this.devices.selectCamera(this.selectedCamera);
-    if (this.selectedSpeaker) await this.devices.selectSpeaker(this.selectedSpeaker);
+  confirm() {
+    if (this.selectedMic) this.devices.selectMic(this.selectedMic);
+    if (this.selectedCamera) this.devices.selectCamera(this.selectedCamera);
+    if (this.selectedSpeaker) this.devices.selectSpeaker(this.selectedSpeaker);
   }
 }
 ```
@@ -110,16 +124,21 @@ export class DevicePickerComponent implements OnInit {
 
 Web sister rules apply, plus Angular-specific:
 
-1. **No `NgZone.run` wrap on `onAudioModesUpdated`.** BehaviorSubject emits but UI doesn't update with OnPush.
+1. **No `NgZone.run` wrap on the device-change events.** BehaviorSubject emits but UI doesn't update with OnPush.
 2. **Service NOT provided in `root`.** Lazy-loaded → device events miss.
 3. **`async pipe` not used.** Manual `subscribe` without `unsubscribe` leaks.
+4. **`await`-ing the device getters/setters.** They are synchronous (`getAudioInputDevices()` returns `MediaDeviceInfo[]`; setters return `void`). `await` on them is a no-op that masks the real (sync) signature.
+5. **Reading `device.id`.** The SDK returns DOM `MediaDeviceInfo` — the identifier is `device.deviceId`.
+6. **Expecting `CometChatCalls.removeEventListener`.** It does not exist. `addEventListener` returns a `() => void`; capture and call it to clean up.
 
 ---
 
 ## Verification checklist
 
 - [ ] `CallDevicesService` provided in root
-- [ ] `NgZone.run` wraps the device-update event
+- [ ] `NgZone.run` wraps the device-update events (`onAudioInputDevicesChanged` / `onAudioOutputDevicesChanged` / `onVideoInputDevicesChanged`)
+- [ ] Listener unsubscribe fns captured and called in `ngOnDestroy` (no `removeEventListener`)
+- [ ] Device getters/setters called WITHOUT `await` (they are sync); options use `device.deviceId`
 - [ ] Picker uses `async` pipe (not manual subscribe)
 - [ ] `ensurePermission()` called before `refresh()` (empty-label fix)
 - [ ] Browser smoke: plug/unplug headphones during call → list updates

package/skills/cometchat-angular-calls/references/group-calls.md

@@ -1,6 +1,8 @@
 # Group calls (meetings) on Angular
 
-Angular wraps the same JS Calls SDK as React/Vue/Svelte; the SDK semantics are identical. The wiring differences are Angular-specific: NgZone for active-speaker updates, `@Input` / `@Output` patterns for participant components, OnPush + `markForCheck` for roster changes.
+Angular wraps the same JS Calls SDK as React/Vue/Svelte; the SDK semantics are identical. The wiring differences are Angular-specific: NgZone for dominant-speaker updates, `@Input` / `@Output` patterns for participant components, OnPush + `markForCheck` for roster changes.
+
+> **v5 event note.** `CometChatCalls.OngoingCallListener` is `@deprecated` in calls-sdk-javascript v5 (use `CometChatCalls.addEventListener(...)`). It still works for roster events (`onUserJoined` / `onUserLeft` / `onUserListUpdated` / `onCallEnded` / `onError`), but there is **no `onActiveSpeakerUpdated` callback on the listener** — the dominant-speaker signal is only available as the `addEventListener` event key `onDominantSpeakerChanged`. The examples below use `addEventListener` for dominant speaker and may keep the listener for roster events.
 
 For SDK-level semantics — capacity limits, bandwidth scaling, moderator actions — see `cometchat-native-calls/references/group-calls.md`. This reference covers the Angular-specific patterns.
 
@@ -160,7 +162,10 @@ export class GroupCallComponent implements OnInit, OnDestroy {
 
   constructor(private zone: NgZone, private cd: ChangeDetectorRef) {}
 
+  private offSpeaker?: () => void;
+
   ngOnInit() {
+    // Roster via the (deprecated but functional) OngoingCallListener:
     const listener = new CometChatCalls.OngoingCallListener({
       onUserListUpdated: (users: Participant[]) => {
         this.zone.run(() => {
@@ -169,14 +174,24 @@ export class GroupCallComponent implements OnInit, OnDestroy {
           this.cd.markForCheck();        // OnPush — must mark
         });
       },
-      onActiveSpeakerUpdated: (uid: string) => {
+    });
+
+    // Dominant speaker is NOT a listener callback — subscribe via addEventListener.
+    // addEventListener returns an unsubscribe fn (there is no removeEventListener).
+    this.offSpeaker = CometChatCalls.addEventListener(
+      "onDominantSpeakerChanged",
+      (participant: { uid: string }) => {
         this.zone.run(() => {
-          // Debounce — see "Debouncing active-speaker" below
-          this.scheduleSpeakerSwap(uid);
+          // Debounce — see "Debouncing dominant-speaker" below
+          this.scheduleSpeakerSwap(participant.uid);
         });
       },
-    });
-    // ... build CallSettings, startSession ...
+    );
+    // ... pass a SessionSettings object + call token to CometChatCalls.joinSession ...
+  }
+
+  ngOnDestroy() {
+    this.offSpeaker?.();
   }
 
   trackByUid(_: number, p: Participant) {
@@ -209,9 +224,9 @@ export class GroupCallComponent implements OnInit, OnDestroy {
 
 ---
 
-## Debouncing active-speaker
+## Debouncing dominant-speaker
 
-Same rule as RN — `onActiveSpeakerUpdated` can fire many times per second in a noisy call. Debounce to 500ms minimum:
+Same rule as RN — `onDominantSpeakerChanged` can fire many times per second in a noisy call. Debounce to 500ms minimum:
 
 ```ts
 private speakerSwapTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -241,9 +256,11 @@ ngOnInit() {
     this.zone.run(() => { this.activeSpeakerUid = uid; this.recomputeLayout(); this.cd.markForCheck(); });
   });
 
-  const listener = new CometChatCalls.OngoingCallListener({
-    onActiveSpeakerUpdated: (uid: string) => this.speakerSubject.next(uid),
-  });
+  // Dominant speaker comes from addEventListener, not the listener object:
+  this.offSpeaker = CometChatCalls.addEventListener(
+    "onDominantSpeakerChanged",
+    (participant: { uid: string }) => this.speakerSubject.next(participant.uid),
+  );
 }
 ```
 
@@ -251,25 +268,28 @@ ngOnInit() {
 
 ## Moderator actions — guarded by group scope
 
+The v5 SDK exposes **`CometChatCalls.muteParticipant(participantId)`** (sync, void) — there is
+no `muteUser` / `removeUser`. **There is NO kick/remove-participant API in the JS Calls SDK** —
+removal must be done at the chat layer (e.g. `CometChat.kickGroupMember`), not via the Calls SDK.
+
 ```ts
 // In your component or a CallControlsService
-async muteParticipant(uid: string) {
+muteParticipant(participantId: string) {
   if (!this.canModerate()) return;
-  await CometChatCalls.muteUser(uid);
+  CometChatCalls.muteParticipant(participantId);   // sync, void — no await
 }
 
-async kickParticipant(uid: string) {
-  if (!this.canModerate()) return;
-  await CometChatCalls.removeUser(uid);
-}
-
-async muteAll() {
+muteAll() {
   if (!this.canModerate()) return;
   for (const p of this.others) {
-    await CometChatCalls.muteUser(p.uid);
+    CometChatCalls.muteParticipant(p.uid);
   }
 }
 
+// NOTE: no kick/remove API exists in @cometchat/calls-sdk-javascript.
+// To eject someone, remove them from the group via the Chat SDK
+// (CometChat.kickGroupMember(...)) — they then lose access to the session.
+
 private canModerate(): boolean {
   const scope = this.group?.getScope();
   return scope === "admin" || scope === "moderator";
@@ -281,7 +301,7 @@ Hide the moderator-only buttons in the template:
 ```html
 <div *ngIf="canModerate()" class="moderator-controls">
   <button (click)="muteAll()">Mute all</button>
-  <button (click)="kickParticipant(p.uid)" *ngFor="let p of others">Kick</button>
+  <button (click)="muteParticipant(p.uid)" *ngFor="let p of others">Mute</button>
 </div>
 ```
 
@@ -321,7 +341,7 @@ async observeBattery() {
     const check = () => {
       if (battery.level < 0.2 && this.callActive) {
         this.zone.run(() => {
-          CometChatCalls.pauseVideo(true);
+          CometChatCalls.pauseVideo();   // no-arg in v5 (pauses local video)
           this.snackBar.open("Video paused — low battery", "Dismiss", { duration: 5000 });
         });
       }
@@ -382,8 +402,9 @@ ngOnInit() {
 
 1. **Roster updates without `trackByUid`** in `*ngFor`. Tiles re-create; video tracks die.
 2. **Skipping `markForCheck`** with OnPush. Roster updates don't render.
-3. **No debounce on active-speaker.** Tiles jitter at 5+ Hz.
+3. **No debounce on dominant-speaker.** Tiles jitter at 5+ Hz.
 4. **Moderator buttons rendered for non-moderators.** SDK rejects but UI is misleading.
+   (Remember: only `muteParticipant` exists — there is no kick/remove in the Calls SDK.)
 5. **`getBattery()` without feature detect.** Firefox/Safari throws.
 6. **Leaving the call doesn't unsubscribe RxJS subjects.** Memory leak across multiple call sessions.
 7. **Group call from a lazy-loaded module.** CallInitService must be eager (cf. `references/lazy-loading-pitfalls.md`).
@@ -394,7 +415,7 @@ ngOnInit() {
 
 - [ ] `*ngFor` over participants uses `trackBy: trackByUid`
 - [ ] OnPush components call `cd.markForCheck()` on roster updates
-- [ ] Active-speaker updates debounced ≥500ms
+- [ ] Dominant-speaker updates (via `addEventListener("onDominantSpeakerChanged", …)`) debounced ≥500ms
 - [ ] All SDK callbacks wrapped in `zone.run`
 - [ ] Moderator controls hidden for non-moderator scopes
 - [ ] Capacity error handled (`ERR_CALL_FULL`) with user-facing snackbar

package/skills/cometchat-angular-calls/references/idle-timeout.md

@@ -9,19 +9,37 @@ Same SDK API as web. Angular-specific delta: NgZone wrap on the timeout event +
 
 ## SDK API
 
-```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)
-  .setIdleTimeoutPeriodAfterPrompt(120_000)
-  .build();
+The idle timeout is configured on the **`SessionSettings` object** passed to
+`joinSession(callToken, sessionSettings, container)`, NOT on the builder.
+
+- The builder (`CallSettingsBuilder`) has a single `setIdleTimeoutPeriod(ms)` method — there is
+  no `setIdleTimeoutPeriodBeforePrompt` / `setIdleTimeoutPeriodAfterPrompt` on it.
+- The before/after split exists ONLY as `SessionSettings` object fields:
+  `idleTimeoutPeriodBeforePrompt` and `idleTimeoutPeriodAfterPrompt`.
+- There is no `setSessionID()` on the builder — the session is identified by the call token
+  produced via `CometChatCalls.generateToken(sessionId, authToken)`.
 
-CometChatCalls.addEventListener("onSessionTimedOut", () => {
+```ts
+// 1. token carries the session id
+const { token } = await CometChatCalls.generateToken(sessionId, authToken);
+
+// 2. idle timeout lives on the SessionSettings object
+const sessionSettings = {
+  sessionType: "VIDEO",
+  idleTimeoutPeriodBeforePrompt: 60_000,
+  idleTimeoutPeriodAfterPrompt: 120_000,
+} as const;
+
+// addEventListener returns an unsubscribe fn — capture it (there is no removeEventListener).
+const off = CometChatCalls.addEventListener("onSessionTimedOut", () => {
   this.zone.run(() => {
     this.router.navigate(["/"]);
     this.snackBar.open("Call ended due to inactivity", "Dismiss", { duration: 5000 });
   });
 });
+
+await CometChatCalls.joinSession(token, sessionSettings, container);
+// later: off();
 ```
 
 `NgZone.run` wrap is mandatory — without it, the navigation + snackbar don't fire because the SDK callback is outside Angular's zone.
@@ -39,7 +57,8 @@ import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
 @Injectable({ providedIn: "root" })
 export class IdleTimeoutService {
-  private listener?: () => void;
+  // addEventListener returns the unsubscribe fn — there is no CometChatCalls.removeEventListener.
+  private off?: () => void;
 
   constructor(
     private zone: NgZone,
@@ -48,20 +67,17 @@ export class IdleTimeoutService {
   ) {}
 
   attachToCallSession() {
-    this.listener = () => {
+    this.off = CometChatCalls.addEventListener("onSessionTimedOut", () => {
       this.zone.run(() => {
         this.router.navigate(["/"]);
         this.snackBar.open("Call ended due to inactivity", "Dismiss", { duration: 5000 });
       });
-    };
-    CometChatCalls.addEventListener("onSessionTimedOut", this.listener);
+    });
   }
 
   detach() {
-    if (this.listener) {
-      CometChatCalls.removeEventListener("onSessionTimedOut", this.listener);
-      this.listener = undefined;
-    }
+    this.off?.();
+    this.off = undefined;
   }
 }
 ```

package/skills/cometchat-angular-calls/references/ngzone-and-async-callbacks.md

@@ -56,6 +56,8 @@ All Calls SDK event listeners. The kit's own components handle this internally;
 
 Conservative rule: **wrap every callback that mutates UI state** in `zone.run`.
 
+> `CometChatCalls.OngoingCallListener` is `@deprecated` in calls-sdk-javascript v5 (prefer `CometChatCalls.addEventListener(...)`); the listener pattern below still works and is shown here because this reference is about NgZone-wrapping. Note that the dominant-speaker signal is NOT a listener callback — subscribe to it via `addEventListener("onDominantSpeakerChanged", …)` (also wrap that handler in `zone.run`).
+
 ```ts
 const listener = new CometChatCalls.OngoingCallListener({
   onUserListUpdated: (userList) => {
@@ -67,12 +69,11 @@ const listener = new CometChatCalls.OngoingCallListener({
   onError: (err) => {
     this.zone.run(() => { this.errorMessage = err.message; });
   },
-  onActiveSpeakerUpdated: (uid) => {
-    this.zone.run(() => { this.activeSpeakerUid = uid; });
-  },
-  onMediaDeviceListUpdated: (devices) => {
-    this.zone.run(() => { this.devices = devices; });
-  },
+});
+
+// Dominant speaker is an addEventListener event key, not a listener callback:
+const offSpeaker = CometChatCalls.addEventListener("onDominantSpeakerChanged", (p) => {
+  this.zone.run(() => { this.activeSpeakerUid = p.uid; });
 });
 ```
 

package/skills/cometchat-angular-calls/references/raise-hand.md

@@ -49,14 +49,19 @@ export class RaiseHandService implements OnDestroy {
     });
   };
 
+  // addEventListener returns an unsubscribe fn — there is NO CometChatCalls.removeEventListener.
+  private offs: Array<() => void> = [];
+
   constructor(private zone: NgZone) {
-    CometChatCalls.addEventListener("onParticipantHandRaised", this.onRaised);
-    CometChatCalls.addEventListener("onParticipantHandLowered", this.onLowered);
+    this.offs.push(
+      CometChatCalls.addEventListener("onParticipantHandRaised", this.onRaised),
+      CometChatCalls.addEventListener("onParticipantHandLowered", this.onLowered),
+    );
   }
 
   ngOnDestroy() {
-    CometChatCalls.removeEventListener("onParticipantHandRaised", this.onRaised);
-    CometChatCalls.removeEventListener("onParticipantHandLowered", this.onLowered);
+    this.offs.forEach(off => off());
+    this.offs = [];
   }
 
   raise() { CometChatCalls.raiseHand(); }