chore(voip): document iOS busy-call helpers; tighten videoconf guard tests

Document why hasActiveCall() and rejectBusyCall() are not used from
AppDelegate during CallKit call-waiting, and type voipBlocksIncomingVideoconf
tests with IClientMediaCall instead of any.

Made-with: Cursor

Author: diegolmello

app/lib/services/voip/voipBlocksIncomingVideoconf.test.ts

@@ -1,8 +1,15 @@
+import type { IClientMediaCall } from '@rocket.chat/media-signaling';
+
 import { voipBlocksIncomingVideoconf } from './voipBlocksIncomingVideoconf';
 
-const mockGetState = jest.fn(() => ({
-	call: null as unknown,
-	nativeAcceptedCallId: null as string | null
+type CallStoreSlice = {
+	call: IClientMediaCall | null;
+	nativeAcceptedCallId: string | null;
+};
+
+const mockGetState = jest.fn((): CallStoreSlice => ({
+	call: null,
+	nativeAcceptedCallId: null
 }));
 
 jest.mock('./useCallStore', () => ({
@@ -21,8 +28,9 @@ describe('voipBlocksIncomingVideoconf', () => {
 	});
 
 	it('returns true when VoIP store has an active call', () => {
+		const activeCall = { callId: 'voip-1' } as unknown as IClientMediaCall;
 		mockGetState.mockReturnValue({
-			call: { callId: 'voip-1' } as any,
+			call: activeCall,
 			nativeAcceptedCallId: null
 		});
 		expect(voipBlocksIncomingVideoconf()).toBe(true);

ios/Libraries/VoipService.swift

@@ -139,6 +139,10 @@ public final class VoipService: NSObject {
 
     /// Returns `true` when CXCallObserver reports any non-ended call (ringing or connected),
     /// including phone, FaceTime, and third-party VoIP.
+    ///
+    /// **Call-waiting (current `AppDelegate+Voip` behavior):** This is **not** called from the PushKit
+    /// path; CallKit handles multiple simultaneous calls. Kept for parity with Android busy detection,
+    /// documentation of `prepareIncomingCall(_:storeEventsForJs:)`, and optional future or test use.
     public static func hasActiveCall() -> Bool {
         configureCallObserverIfNeeded()
         return callObserver.calls.contains { !$0.hasEnded }
@@ -533,6 +537,10 @@ public final class VoipService: NSObject {
 
     /// Rejects an incoming call because the user is already on another call.
     /// Must be called **after** `reportNewIncomingCall` (PushKit requirement).
+    ///
+    /// **Call-waiting:** `AppDelegate+Voip` does **not** invoke this; second rings are shown in CallKit
+    /// instead of auto-rejecting. Same rationale as `hasActiveCall()` — API remains for Android-aligned
+    /// flows, `storeEventsForJs: false` cleanup, and future wiring.
     public static func rejectBusyCall(_ payload: VoipPayload) {
         cancelIncomingCallTimeout(for: payload.callId)
         clearTrackedIncomingCall(for: payload.callUUID)