@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-angular-calls/references/lazy-loading-pitfalls.md

@@ -0,0 +1,205 @@
+# Lazy loading + calls in Angular — pitfalls
+
+Calls have a tighter relationship with bootstrap than chat does. Lazy-loading the calls module breaks several invariants.
+
+---
+
+## The core problem
+
+`APP_INITIALIZER` runs at app bootstrap, before any router activates. The Calls SDK init must complete BEFORE incoming calls can fire — otherwise the listener doesn't exist when the first call rings.
+
+If you lazy-load the calls module:
+
+```ts
+// app-routing.module.ts
+{ path: "calls", loadChildren: () => import("./calls/calls.module").then(m => m.CallsModule) }
+```
+
+Then `CallInitService` (which lives in `CallsModule`) doesn't exist at bootstrap. APP_INITIALIZER can't reference it. Two failure modes:
+
+1. **Init never runs** — until the user navigates to `/calls`, the SDK is uninitialized. Incoming calls miss.
+2. **Race condition** — user navigates to `/calls`, the lazy module loads, init runs, but a call had been incoming during the navigation gap. That call is lost.
+
+---
+
+## Fix: split the service from the component
+
+Keep `CallInitService` in `AppModule` (eager). Keep the call UI components in `CallsModule` (lazy).
+
+```ts
+// app.module.ts (eager)
+@NgModule({
+  providers: [
+    CallInitService,                              // EAGER — service is at bootstrap
+    {
+      provide: APP_INITIALIZER,
+      useFactory: (svc: CallInitService) => () => svc.init(),
+      deps: [CallInitService],
+      multi: true,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+```ts
+// calls/calls.module.ts (lazy)
+@NgModule({
+  declarations: [
+    OngoingCallComponent,
+    CallLogsComponent,
+    CallButtonComponent,
+  ],
+  imports: [
+    RouterModule.forChild([
+      { path: "ongoing/:id", component: OngoingCallComponent, canDeactivate: [CallDeactivateGuard] },
+      { path: "logs", component: CallLogsComponent },
+    ]),
+  ],
+})
+export class CallsModule {}
+```
+
+The components reference `CallInitService` via DI; Angular finds it from the parent injector (AppModule).
+
+---
+
+## Pitfall 2: `<cometchat-incoming-call>` in a lazy module
+
+Incoming calls must ring on every screen — not just `/calls`. Mounting `<cometchat-incoming-call>` inside `CallsModule`'s components means:
+
+- User on `/dashboard` → no incoming-call listener → calls miss
+- User navigates to `/calls/logs` → listener mounts → calls now ring
+- User navigates back to `/dashboard` → listener unmounts → calls miss again
+
+**Fix:** mount `<cometchat-incoming-call>` in `AppComponent`'s template (the root of the application, NOT in any feature module):
+
+```html
+<!-- app.component.html -->
+<cometchat-incoming-call></cometchat-incoming-call>
+<router-outlet></router-outlet>
+```
+
+`AppModule` must import enough of `@cometchat/chat-uikit-angular` to render this selector — usually `CometChatUIKitModule.forRoot({...})`. Schemas option `CUSTOM_ELEMENTS_SCHEMA` works too.
+
+---
+
+## Pitfall 3: standalone components + lazy-loaded calls
+
+Angular 14+ standalone components don't have a parent `NgModule`. The DI tree is different — APP_INITIALIZER lives at the bootstrap providers level:
+
+```ts
+// main.ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    CallInitService,                           // root-provided — visible everywhere
+    {
+      provide: APP_INITIALIZER,
+      useFactory: (svc: CallInitService) => () => svc.init(),
+      deps: [CallInitService],
+      multi: true,
+    },
+    provideRouter([
+      // Lazy-loaded standalone routes
+      { path: "calls/ongoing/:id", loadComponent: () => import("./calls/ongoing-call.component").then(m => m.OngoingCallComponent) },
+    ]),
+  ],
+});
+```
+
+The lazy `loadComponent` works fine because `CallInitService` is at the root.
+
+`<cometchat-incoming-call>` is a standalone component too:
+
+```ts
+// app.component.ts
+import { CometChatIncomingCallComponent } from "@cometchat/chat-uikit-angular";
+
+@Component({
+  standalone: true,
+  selector: "app-root",
+  imports: [RouterOutlet, CometChatIncomingCallComponent],
+  template: `
+    <cometchat-incoming-call></cometchat-incoming-call>
+    <router-outlet></router-outlet>
+  `,
+})
+export class AppComponent {}
+```
+
+(Verify the export name in your installed `@cometchat/chat-uikit-angular` version — may differ between minor releases.)
+
+---
+
+## Pitfall 4: SSR (Angular Universal)
+
+The Calls SDK uses browser-only APIs (`getUserMedia`, `RTCPeerConnection`). If your app uses Angular Universal, the calls service must NOT initialize on the server:
+
+```ts
+import { isPlatformBrowser } from "@angular/common";
+import { Inject, PLATFORM_ID } from "@angular/core";
+
+@Injectable({ providedIn: "root" })
+export class CallInitService {
+  constructor(@Inject(PLATFORM_ID) private platformId: object) {}
+
+  async init(): Promise<void> {
+    if (!isPlatformBrowser(this.platformId)) return;        // skip on server
+    // ... actual init
+  }
+}
+```
+
+Without this guard, the SSR build crashes with `ReferenceError: window is not defined` at boot.
+
+---
+
+## Pitfall 5: Multiple `APP_INITIALIZER`s
+
+If your project already uses `APP_INITIALIZER` for chat init, calls init goes alongside — not as a replacement:
+
+```ts
+providers: [
+  ChatInitService,
+  CallInitService,
+  {
+    provide: APP_INITIALIZER,
+    useFactory: (chat: ChatInitService) => () => chat.init(),
+    deps: [ChatInitService],
+    multi: true,                               // ← multi: true is critical
+  },
+  {
+    provide: APP_INITIALIZER,
+    useFactory: (calls: CallInitService) => () => calls.init(),
+    deps: [CallInitService],
+    multi: true,
+  },
+]
+```
+
+Both register; both run before bootstrap. They run in registration order — chat first, then calls (matches rule 1.1's chat-init-before-calls-init).
+
+---
+
+## Pitfall 6: Forgetting the route deactivate guard for ongoing calls
+
+Without `CanDeactivate`, the user can route away mid-call and the call screen unmounts but the SDK session keeps running. Camera light stays on (rule 1.5 violation).
+
+```ts
+// calls-routing.module.ts
+{ path: "ongoing/:id", component: OngoingCallComponent, canDeactivate: [CallDeactivateGuard] }
+```
+
+The guard is in `references/custom-ui.md`.
+
+---
+
+## Summary
+
+| Place | What goes here |
+|---|---|
+| `AppModule` (eager) | `CallInitService`, `APP_INITIALIZER`, `<cometchat-incoming-call>` |
+| `CallsModule` (lazy) | UI components (OngoingCall, CallLogs, CallButton), feature routes |
+| App root template | `<cometchat-incoming-call>` mounted above `<router-outlet>` |
+| Routes | `canDeactivate` guard on the ongoing-call route |
+| SSR | `isPlatformBrowser` check inside init service |

package/skills/cometchat-angular-calls/references/migration-v4-to-v5.md

@@ -0,0 +1,53 @@
+# Calls SDK v4 → v5 migration (Angular)
+
+Angular ships the same `@cometchat/calls-sdk-javascript` as React/Vue, so the migration steps are identical. Angular-specific deltas: NgZone wrapping for the new event listeners.
+
+**Read first:** `cometchat-react-calls/references/migration-v4-to-v5.md` — full step-by-step (init, login, settings, events, methods).
+
+---
+
+## Step 1 — Bump the package
+
+```bash
+npm install @cometchat/calls-sdk-javascript@5
+```
+
+---
+
+## Angular-specific delta: NgZone for new event listeners
+
+When migrating from `OngoingCallListener` to `addEventListener`, Angular needs `NgZone.run` to update OnPush components — listeners fire outside Angular's zone:
+
+```ts
+@Injectable({ providedIn: "root" })
+export class CallEventService {
+  constructor(private zone: NgZone) {
+    // v4 — listener was inside CometChatCalls.OngoingCallListener; if your
+    // current code already wraps callbacks with NgZone.run, keep that.
+    // v5 — addEventListener fires outside zone:
+    CometChatCalls.addEventListener("onSessionLeft", () => {
+      this.zone.run(() => this.onSessionLeft$.next());
+    });
+    CometChatCalls.addEventListener("onParticipantJoined", (p) => {
+      this.zone.run(() => this.participantJoined$.next(p));
+    });
+  }
+}
+```
+
+If you skip the `NgZone.run` wrap, OnPush components don't re-render when call state changes.
+
+---
+
+## Verification checklist
+
+- [ ] All v5 event listeners wrapped in `NgZone.run`
+- [ ] All sister checks from the canonical migration guide
+
+---
+
+## Pointers
+
+- Canonical migration: `cometchat-react-calls/references/migration-v4-to-v5.md`
+- Canonical Web Push event handling: `references/ngzone-and-async-callbacks.md`
+- https://www.cometchat.com/docs/calls/javascript/migration-guide-v5

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

@@ -0,0 +1,183 @@
+# NgZone + async SDK callbacks — the Angular calls gotcha
+
+Angular's change detection runs inside `NgZone`. Callbacks that fire *outside* NgZone don't trigger change detection — UI doesn't update. The Calls SDK fires lots of callbacks from native bridges (WebRTC, browser MediaStream events), and those bridges escape the zone.
+
+If your custom call UI seems "frozen" — call ends but the screen stays — this is almost always the cause.
+
+---
+
+## Symptom
+
+```ts
+// OngoingCallComponent
+ngOnInit() {
+  CometChatCalls.joinSession(token, settings, container);  // v5 canonical (startSession is a deprecated shim)
+
+  // This callback is registered with the SDK, which is registered with WebRTC,
+  // which is a native browser API outside Angular's zone
+  callListener.onCallEnded = () => {
+    this.callEnded = true;       // ← variable updates
+    this.cleanup();              // ← runs
+    // BUT: change detection doesn't fire. The template doesn't re-render.
+    // User sees: "End" button still showing, no "Call ended" message.
+  };
+}
+```
+
+---
+
+## Fix
+
+Wrap the callback body in `NgZone.run`:
+
+```ts
+import { NgZone } from "@angular/core";
+
+constructor(private zone: NgZone) {}
+
+ngOnInit() {
+  // ...
+  callListener.onCallEnded = () => {
+    this.zone.run(() => {
+      this.callEnded = true;
+      this.cleanup();
+    });
+  };
+}
+```
+
+Now change detection runs after the variable updates; template re-renders.
+
+---
+
+## Which callbacks need NgZone.run?
+
+All Calls SDK event listeners. The kit's own components handle this internally; custom code that subscribes to the SDK directly does NOT.
+
+Conservative rule: **wrap every callback that mutates UI state** in `zone.run`.
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onUserListUpdated: (userList) => {
+    this.zone.run(() => { this.participants = userList; });
+  },
+  onCallEnded: () => {
+    this.zone.run(() => { this.callEnded = true; this.cleanup(); });
+  },
+  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; });
+  },
+});
+```
+
+If a callback only triggers a side effect (logging, analytics) without UI changes, NgZone.run is not strictly required — but harmless.
+
+---
+
+## Alternative: ChangeDetectorRef.detectChanges
+
+If you want to avoid NgZone for performance reasons (zone.run is cheap but adds overhead in hot paths), use `ChangeDetectorRef.detectChanges`:
+
+```ts
+import { ChangeDetectorRef } from "@angular/core";
+
+constructor(private cd: ChangeDetectorRef) {}
+
+ngOnInit() {
+  callListener.onCallEnded = () => {
+    this.callEnded = true;
+    this.cleanup();
+    this.cd.detectChanges();   // run change detection just for this component subtree
+  };
+}
+```
+
+Pros: scoped to the component (NgZone is global).
+Cons: if you have parent component bindings that depend on this state, they don't update. Use NgZone.run for cross-component state changes.
+
+For 95% of cases, NgZone.run is the right answer.
+
+---
+
+## Async/await inside callbacks
+
+If your callback is `async`, wrap the whole function:
+
+```ts
+callListener.onCallEnded = async () => {
+  await this.zone.run(async () => {
+    await this.savePostCallAnalytics();
+    this.callEnded = true;
+    this.cleanup();
+  });
+};
+```
+
+Or simpler — use a plain method and let zone.js patch async automatically:
+
+```ts
+callListener.onCallEnded = () => {
+  this.zone.run(() => this.handleCallEnded());
+};
+
+private async handleCallEnded() {
+  await this.savePostCallAnalytics();
+  this.callEnded = true;
+  this.cleanup();
+}
+```
+
+Inside `handleCallEnded`, change detection fires automatically because zone.js patches `await`.
+
+---
+
+## How to detect this bug
+
+Add a debug log inside the callback. If the log fires but the UI doesn't update, you're outside zone:
+
+```ts
+callListener.onCallEnded = () => {
+  console.log("[debug] onCallEnded fired", new Date().toISOString());
+  this.callEnded = true;
+};
+```
+
+If "fired" appears in console but the template still shows the call as active, wrap in zone.run.
+
+---
+
+## OnPush change detection
+
+If your component uses `ChangeDetectionStrategy.OnPush`, NgZone.run alone isn't enough — OnPush only re-renders on `@Input` changes or explicit markForCheck. Combine:
+
+```ts
+import { ChangeDetectionStrategy, ChangeDetectorRef } from "@angular/core";
+
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class OngoingCallComponent {
+  constructor(private zone: NgZone, private cd: ChangeDetectorRef) {}
+
+  ngOnInit() {
+    callListener.onCallEnded = () => {
+      this.zone.run(() => {
+        this.callEnded = true;
+        this.cd.markForCheck();
+      });
+    };
+  }
+}
+```
+
+---
+
+## When the kit fires NgZone-correctly
+
+The CometChat Angular UI Kit (`@cometchat/chat-uikit-angular`) handles this internally. If you only use `<cometchat-incoming-call>`, `<cometchat-ongoing-call>`, etc. — no manual NgZone needed. The bug only bites when you write custom subscriptions to `CometChatCalls.*` callbacks.