agora-appbuilder-core 4.1.24 → 4.1.25-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agora-appbuilder-core",
-  "version": "4.1.24",
+  "version": "4.1.25-beta.1",
   "description": "React Native template for RTE app builder",
   "main": "index.js",
   "files": [

package/template/defaultConfig.js

@@ -77,8 +77,8 @@ const DefaultConfig = {
   CHAT_ORG_NAME: "",
   CHAT_APP_NAME: "",
   CHAT_URL: "",
-  CLI_VERSION: "3.1.24",
-  CORE_VERSION: "4.1.24",
+  CLI_VERSION: "3.1.25-beta.1",
+  CORE_VERSION: "4.1.25-beta.1",
   DISABLE_LANDSCAPE_MODE: false,
   STT_AUTO_START: false,
   CLOUD_RECORDING_AUTO_START: false,

package/template/src/subComponents/caption/__tests__/transcriptStreamListener.test.ts

@@ -0,0 +1,47 @@
+import {
+  registerTranscriptStreamListener,
+  removeTranscriptStreamListener,
+  TranscriptStreamEngine,
+} from '../transcriptStreamListener';
+
+describe('transcript stream listener lifecycle', () => {
+  it('tracks and removes a native listener when addListener returns void', () => {
+    const listener = jest.fn();
+    const engine: TranscriptStreamEngine = {
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+    };
+
+    const registration = registerTranscriptStreamListener(engine, listener);
+
+    expect(registration).toEqual({subscription: null});
+    expect(engine.addListener).toHaveBeenCalledTimes(1);
+    expect(engine.addListener).toHaveBeenCalledWith(
+      'onStreamMessage',
+      listener,
+    );
+
+    removeTranscriptStreamListener(engine, listener, registration, false);
+
+    expect(engine.removeListener).toHaveBeenCalledTimes(1);
+    expect(engine.removeListener).toHaveBeenCalledWith(
+      'onStreamMessage',
+      listener,
+    );
+  });
+
+  it('uses the subscription returned by the web bridge', () => {
+    const listener = jest.fn();
+    const remove = jest.fn();
+    const engine: TranscriptStreamEngine = {
+      addListener: jest.fn(() => ({remove})),
+      removeListener: jest.fn(),
+    };
+
+    const registration = registerTranscriptStreamListener(engine, listener);
+    removeTranscriptStreamListener(engine, listener, registration, true);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+    expect(engine.removeListener).not.toHaveBeenCalled();
+  });
+});

package/template/src/subComponents/caption/transcriptJourney.ts

@@ -0,0 +1 @@
+export const TRANSCRIPT_JOURNEY = '[TRANSCRIPT_JOURNEY]';

package/template/src/subComponents/caption/transcriptStreamListener.ts

@@ -0,0 +1,50 @@
+export type TranscriptStreamListener = (...args: any[]) => void;
+
+type TranscriptStreamSubscription = {
+  remove: () => void;
+};
+
+export type TranscriptStreamEngine = {
+  addListener: (
+    event: 'onStreamMessage',
+    listener: TranscriptStreamListener,
+  ) => unknown;
+  removeListener: (
+    event: 'onStreamMessage',
+    listener: TranscriptStreamListener,
+  ) => void;
+};
+
+export type TranscriptStreamListenerRegistration = {
+  subscription: TranscriptStreamSubscription | null;
+};
+
+export const registerTranscriptStreamListener = (
+  engine: TranscriptStreamEngine,
+  listener: TranscriptStreamListener,
+): TranscriptStreamListenerRegistration => {
+  const result = engine.addListener('onStreamMessage', listener);
+  const subscription =
+    result &&
+    typeof (result as TranscriptStreamSubscription).remove === 'function'
+      ? (result as TranscriptStreamSubscription)
+      : null;
+
+  // Native Agora returns void from addListener. The registration object is our
+  // platform-independent proof that registration completed successfully.
+  return {subscription};
+};
+
+export const removeTranscriptStreamListener = (
+  engine: TranscriptStreamEngine,
+  listener: TranscriptStreamListener,
+  registration: TranscriptStreamListenerRegistration,
+  web: boolean,
+) => {
+  if (web) {
+    registration.subscription?.remove();
+    return;
+  }
+
+  engine.removeListener('onStreamMessage', listener);
+};

package/template/src/subComponents/caption/useCaption.tsx

@@ -21,6 +21,13 @@ import {useRoomInfo} from '../../components/room-info/useRoomInfo';
 import {useContent, useRtc} from 'customization-api';
 import useStreamMessageUtils from './useStreamMessageUtils';
 import {isWebInternal} from '../../utils/common';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
+import {
+  registerTranscriptStreamListener,
+  removeTranscriptStreamListener,
+  TranscriptStreamEngine,
+  TranscriptStreamListenerRegistration,
+} from './transcriptStreamListener';
 
 // Types
 type GlobalSttState = {
@@ -320,22 +327,20 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       prevSpeakerRef,
       selectedTranslationLanguageRef,
     });
-  const transcriptListenerSubscriptionRef = React.useRef<{
-    remove: () => void;
-  } | null>(null);
-
-  const handleStreamMessageCallback = React.useCallback(
-    (...args: any[]) => {
-      if (isWebInternal()) {
-        const [uid, data] = args;
-        streamMessageCallback([uid, data]);
-      } else {
-        const [, uid, , data] = args;
-        streamMessageCallback([uid, data]);
-      }
-    },
-    [streamMessageCallback],
-  );
+  const streamMessageCallbackRef = React.useRef(streamMessageCallback);
+  streamMessageCallbackRef.current = streamMessageCallback;
+  const transcriptListenerRegistrationRef =
+    React.useRef<TranscriptStreamListenerRegistration | null>(null);
+
+  const handleStreamMessageCallback = React.useCallback((...args: any[]) => {
+    if (isWebInternal()) {
+      const [uid, data] = args;
+      streamMessageCallbackRef.current([uid, data]);
+    } else {
+      const [, uid, , data] = args;
+      streamMessageCallbackRef.current([uid, data]);
+    }
+  }, []);
 
   // Register once for the lifetime of the active call. Keeping collection in
   // the provider makes it independent of whether caption/transcript UI is open.
@@ -343,24 +348,73 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     if (
       !$config.ENABLE_STT ||
       !callActive ||
-      transcriptListenerSubscriptionRef.current
+      transcriptListenerRegistrationRef.current
     ) {
       return;
     }
 
-    transcriptListenerSubscriptionRef.current = RtcEngineUnsafe.addListener(
-      'onStreamMessage',
-      handleStreamMessageCallback,
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} stream listener registration requested`,
+      {stage: 'listener_registration', outcome: 'started'},
     );
-    setIsSTTListenerAdded(true);
-  }, [RtcEngineUnsafe, callActive, handleStreamMessageCallback]);
+    try {
+      transcriptListenerRegistrationRef.current =
+        registerTranscriptStreamListener(
+          RtcEngineUnsafe as unknown as TranscriptStreamEngine,
+          handleStreamMessageCallback,
+        );
+      setIsSTTListenerAdded(true);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registered`,
+        {stage: 'listener_registration', outcome: 'success'},
+      );
+    } catch (error) {
+      logger.error(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registration failed`,
+        {
+          stage: 'listener_registration',
+          outcome: 'failure',
+          error: error ?? null,
+        },
+      );
+      return;
+    }
 
-  React.useEffect(() => {
     return () => {
-      transcriptListenerSubscriptionRef.current?.remove();
-      transcriptListenerSubscriptionRef.current = null;
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener cleanup requested`,
+        {
+          stage: 'listener_cleanup',
+          outcome: 'started',
+          listenerRegistered: !!transcriptListenerRegistrationRef.current,
+        },
+      );
+      if (transcriptListenerRegistrationRef.current) {
+        removeTranscriptStreamListener(
+          RtcEngineUnsafe as unknown as TranscriptStreamEngine,
+          handleStreamMessageCallback,
+          transcriptListenerRegistrationRef.current,
+          isWebInternal(),
+        );
+      }
+      transcriptListenerRegistrationRef.current = null;
+      setIsSTTListenerAdded(false);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener removed and local references cleared`,
+        {stage: 'listener_cleanup', outcome: 'completed'},
+      );
     };
-  }, []);
+  }, [RtcEngineUnsafe, callActive, handleStreamMessageCallback]);
 
   const flushPendingTranscript = React.useCallback(async () => {
     await flushStreamMessageQueue();
@@ -393,12 +447,17 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   const updateErrorLabel = useString(sttUpdateError)();
 
   // --- Derived readiness flag for STT ---
+  const localUidReady = !!localUid;
+  const localBotUidReady = !!localBotUid;
+  const rtmJoined = !!hasUserJoinedRTM;
+  const activeCallReady = !!callActive;
+  const roomInfoReady = !!(roomId?.host || roomId?.attendee);
   const sttDepsReady =
-    !!localUid &&
-    !!localBotUid &&
-    !!hasUserJoinedRTM &&
-    !!callActive &&
-    !!(roomId?.host || roomId?.attendee);
+    localUidReady &&
+    localBotUidReady &&
+    rtmJoined &&
+    activeCallReady &&
+    roomInfoReady;
 
   const sttStartGuardRef = React.useRef(false);
   const sttAutoStartGuardRef = React.useRef(false);
@@ -409,6 +468,46 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     sttDepsReadyRef.current = sttDepsReady;
   }, [sttDepsReady]);
 
+  React.useEffect(() => {
+    const missingDependencies = [
+      !localUidReady && 'localUid',
+      !localBotUidReady && 'localBotUid',
+      !rtmJoined && 'RTM',
+      !activeCallReady && 'activeCall',
+      !roomInfoReady && 'roomInfo',
+      !isSTTListenerAdded && 'streamListener',
+    ].filter(Boolean);
+    const transcriptReady = sttDepsReady && isSTTListenerAdded;
+
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} STT readiness: ${
+        transcriptReady
+          ? 'READY'
+          : `WAITING (missing: ${missingDependencies.join(', ')})`
+      }`,
+      {
+        stage: 'stt_readiness',
+        outcome: transcriptReady ? 'ready' : 'waiting',
+        localUidReady,
+        localBotUidReady,
+        rtmJoined,
+        callActive: activeCallReady,
+        roomInfoReady,
+        listenerRegistered: isSTTListenerAdded,
+      },
+    );
+  }, [
+    activeCallReady,
+    isSTTListenerAdded,
+    localBotUidReady,
+    localUidReady,
+    roomInfoReady,
+    rtmJoined,
+    sttDepsReady,
+  ]);
+
   React.useEffect(() => {
     if (sttDepsReadyRef.current && !hasFlushedSttQueueRef.current) {
       hasFlushedSttQueueRef.current = true;