agora-appbuilder-core 4.1.20 → 4.1.21

package/template/src/subComponents/caption/__tests__/sttSessionId.web.test.ts

@@ -0,0 +1,190 @@
+import {beforeEach, describe, expect, it, jest} from '@jest/globals';
+
+jest.mock('../../../rtm/RTMEngine', () => ({
+  __esModule: true,
+  default: {
+    getInstance: jest.fn(),
+  },
+}));
+
+jest.mock('../../../utils/getUniqueID', () => ({
+  __esModule: true,
+  default: jest.fn(() => 'default-candidate'),
+}));
+
+import {
+  createSTTSessionCoordinator,
+  STT_SESSION_ID_KEY,
+} from '../sttSessionId.web';
+
+const channelMetadata = (value?: string, revision = 7) => ({
+  timestamp: 100,
+  channelName: 'room',
+  channelType: 1,
+  majorRevision: revision,
+  itemCount: value ? 1 : 0,
+  items: value
+    ? [
+        {
+          key: STT_SESSION_ID_KEY,
+          value,
+          revision,
+          authorUserId: '1',
+          updateTs: 99,
+        },
+      ]
+    : [],
+});
+
+const presence = (...userIds: string[]) => ({
+  timestamp: 100,
+  totalOccupancy: userIds.length,
+  occupants: userIds.map(userId => ({
+    userId,
+    statesCount: 0,
+    states: [],
+  })),
+  nextPage: '',
+});
+
+const createHarness = () => {
+  const storage = {
+    getChannelMetadata: jest.fn<any>(),
+    setChannelMetadata: jest.fn<any>(),
+    removeChannelMetadata: jest.fn<any>(),
+  };
+  const rtmPresence = {
+    getOnlineUsers: jest.fn<any>(),
+  };
+  const createId = jest.fn(() => 'candidate');
+  const wait = jest.fn(async () => {});
+  const coordinator = createSTTSessionCoordinator({
+    getClient: () => ({storage, presence: rtmPresence} as any),
+    createId,
+    wait,
+  });
+
+  return {coordinator, createId, rtmPresence, storage, wait};
+};
+
+describe('web STT session coordinator', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('reuses existing channel metadata without writing', async () => {
+    const {coordinator, storage} = createHarness();
+    storage.getChannelMetadata.mockResolvedValue(
+      channelMetadata('existing-session'),
+    );
+
+    await expect(coordinator.ensureSTTSessionId('room')).resolves.toBe(
+      'existing-session',
+    );
+    expect(storage.setChannelMetadata).not.toHaveBeenCalled();
+  });
+
+  it('shares one revision-zero creation across concurrent local calls', async () => {
+    const {coordinator, storage} = createHarness();
+    storage.getChannelMetadata.mockResolvedValue(channelMetadata());
+    storage.setChannelMetadata.mockResolvedValue({
+      timestamp: 100,
+      channelName: 'room',
+      channelType: 1,
+    });
+
+    const [first, second] = await Promise.all([
+      coordinator.ensureSTTSessionId('room'),
+      coordinator.ensureSTTSessionId('room'),
+    ]);
+
+    expect(first).toBe('candidate');
+    expect(second).toBe('candidate');
+    expect(storage.setChannelMetadata).toHaveBeenCalledTimes(1);
+    expect(storage.setChannelMetadata).toHaveBeenCalledWith(
+      'room',
+      1,
+      {
+        items: [
+          {
+            key: STT_SESSION_ID_KEY,
+            value: 'candidate',
+            revision: 0,
+          },
+        ],
+      },
+      {addUserId: true, addTimeStamp: true},
+    );
+  });
+
+  it('re-reads and uses the winning value after a create conflict', async () => {
+    const {coordinator, storage} = createHarness();
+    storage.getChannelMetadata
+      .mockResolvedValueOnce(channelMetadata())
+      .mockResolvedValueOnce(channelMetadata('winner-session'));
+    storage.setChannelMetadata.mockRejectedValue(
+      new Error('revision conflict'),
+    );
+
+    await expect(coordinator.ensureSTTSessionId('room')).resolves.toBe(
+      'winner-session',
+    );
+  });
+
+  it('fails after three reads instead of returning a local fallback', async () => {
+    const {coordinator, storage, wait} = createHarness();
+    storage.getChannelMetadata.mockRejectedValue(new Error('RTM unavailable'));
+
+    await expect(coordinator.ensureSTTSessionId('room')).rejects.toThrow(
+      'Unable to resolve the shared STT session ID',
+    );
+    expect(storage.getChannelMetadata).toHaveBeenCalledTimes(3);
+    expect(storage.setChannelMetadata).not.toHaveBeenCalled();
+    expect(wait).toHaveBeenNthCalledWith(1, 100);
+    expect(wait).toHaveBeenNthCalledWith(2, 250);
+  });
+
+  it('keeps metadata while another RTM participant is present', async () => {
+    const {coordinator, rtmPresence, storage} = createHarness();
+    rtmPresence.getOnlineUsers.mockResolvedValue(presence('1', '2'));
+
+    await expect(
+      coordinator.clearSTTSessionIdIfLast('room', '1'),
+    ).resolves.toBe(false);
+    expect(storage.getChannelMetadata).not.toHaveBeenCalled();
+    expect(storage.removeChannelMetadata).not.toHaveBeenCalled();
+  });
+
+  it('stops STT before final revision-aware metadata removal', async () => {
+    const {coordinator, rtmPresence, storage} = createHarness();
+    const calls: string[] = [];
+    rtmPresence.getOnlineUsers.mockResolvedValue(presence('1'));
+    storage.getChannelMetadata.mockResolvedValue(
+      channelMetadata('session-a', 9),
+    );
+    storage.removeChannelMetadata.mockImplementation(async () => {
+      calls.push('remove');
+      return {timestamp: 100, channelName: 'room', channelType: 1};
+    });
+
+    await coordinator.cleanupSTTSessionOnEnd('room', '1', true, async () => {
+      calls.push('stop');
+    });
+
+    expect(calls).toEqual(['stop', 'remove']);
+    expect(rtmPresence.getOnlineUsers).toHaveBeenCalledTimes(3);
+    expect(storage.removeChannelMetadata).toHaveBeenCalledWith('room', 1, {
+      data: {
+        items: [
+          {
+            key: STT_SESSION_ID_KEY,
+            value: '',
+            revision: 9,
+          },
+        ],
+      },
+      addUserId: true,
+      addTimeStamp: true,
+    });
+  });
+});

package/template/src/subComponents/caption/__tests__/useSTTAPI.test.tsx

@@ -0,0 +1,129 @@
+import React from 'react';
+import TestRenderer, {act} from 'react-test-renderer';
+import {beforeEach, describe, expect, it, jest} from '@jest/globals';
+
+jest.mock('../sttSessionId', () => ({
+  ensureSTTSessionId: jest.fn(),
+}));
+
+jest.mock('../../../components/StorageContext', () => {
+  const ReactModule = require('react');
+  return {
+    __esModule: true,
+    default: ReactModule.createContext({store: {token: 'token'}}),
+  };
+});
+
+jest.mock('../../../components/room-info/useRoomInfo', () => ({
+  useRoomInfo: () => ({data: {roomId: {host: 'phrase'}}}),
+}));
+
+jest.mock('../../../../agora-rn-uikit', () => {
+  const ReactModule = require('react');
+  return {
+    PropsContext: ReactModule.createContext({
+      rtcProps: {channel: 'room', encryption: {mode: 8}},
+    }),
+    useLocalUid: () => 123,
+  };
+});
+
+jest.mock('../../../logger/AppBuilderLogger', () => ({
+  LogSource: {NetworkRest: 'NetworkRest'},
+  logger: {
+    getSessionId: () => 'logging-session',
+    log: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+jest.mock('../../../utils/getUniqueID', () => ({
+  __esModule: true,
+  default: () => 'request-id',
+}));
+
+import useSTTAPI from '../useSTTAPI';
+import {ensureSTTSessionId} from '../sttSessionId';
+
+const mockEnsureSTTSessionId = ensureSTTSessionId as jest.Mock<any>;
+
+const translationConfig = {
+  source: ['en-US'],
+  targets: ['de-DE'],
+} as any;
+
+const renderHook = async () => {
+  let api!: ReturnType<typeof useSTTAPI>;
+  let renderer!: TestRenderer.ReactTestRenderer;
+
+  await act(async () => {
+    renderer = TestRenderer.create(
+      <React.Fragment>
+        {React.createElement(() => {
+          api = useSTTAPI();
+          return null;
+        })}
+      </React.Fragment>,
+    );
+  });
+
+  return {api, renderer};
+};
+
+describe('useSTTAPI session coordination', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    global.fetch = jest.fn<any>(async () => ({
+      json: async () => ({}),
+    }));
+  });
+
+  it('does not call STT when the shared session ID cannot be resolved', async () => {
+    mockEnsureSTTSessionId.mockRejectedValue(new Error('RTM unavailable'));
+    const {api, renderer} = await renderHook();
+
+    let response;
+    await act(async () => {
+      response = await api.start(900000123, translationConfig);
+    });
+
+    expect(response).toMatchObject({
+      success: false,
+      error: {message: 'RTM unavailable'},
+    });
+    expect(mockEnsureSTTSessionId).toHaveBeenCalledWith('room');
+    expect(global.fetch).not.toHaveBeenCalled();
+    renderer.unmount();
+  });
+
+  it('adds the shared ID to start, update, and stop while retaining the logging header', async () => {
+    mockEnsureSTTSessionId.mockResolvedValue('shared-session');
+    const {api, renderer} = await renderHook();
+
+    await act(async () => {
+      await api.start(900000123, translationConfig);
+      await api.update(900000123, translationConfig);
+      await api.stop(900000123);
+    });
+
+    expect(global.fetch).toHaveBeenCalledTimes(3);
+    expect(mockEnsureSTTSessionId).toHaveBeenCalledTimes(3);
+    const fetchCalls = (global.fetch as jest.Mock<any>).mock.calls as [
+      string,
+      {body: string; headers: Record<string, string>},
+    ][];
+    for (const [, options] of fetchCalls) {
+      expect(JSON.parse(options.body)).toMatchObject({
+        passphrase: 'phrase',
+        session_id: 'shared-session',
+      });
+      expect(options.headers['X-Session-Id']).toBe('logging-session');
+    }
+    expect(fetchCalls.map(([url]) => url)).toEqual([
+      expect.stringMatching(/\/startv7$/),
+      expect.stringMatching(/\/update$/),
+      expect.stringMatching(/\/stopv7$/),
+    ]);
+    renderer.unmount();
+  });
+});

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

@@ -0,0 +1,54 @@
+import {type LanguageTranslationConfig} from './useCaption';
+
+export type STTMethod = 'startv7' | 'update' | 'stopv7';
+
+interface BuildSTTRequestBodyOptions {
+  method: STTMethod;
+  botUid: number;
+  passphrase: string;
+  encryptionMode: number | null;
+  localUid: string | number;
+  channelName: string;
+  translationConfig?: LanguageTranslationConfig;
+  resolveSessionId: (channelName: string) => Promise<string | undefined>;
+}
+
+export const buildSTTRequestBody = async (
+  options: BuildSTTRequestBodyOptions,
+): Promise<Record<string, any>> => {
+  const requestBody: Record<string, any> = {
+    passphrase: options.passphrase,
+    dataStream_uid: options.botUid,
+    encryption_mode: options.encryptionMode,
+  };
+
+  const sessionId = await options.resolveSessionId(options.channelName);
+  if (!sessionId) {
+    throw new Error('Unable to resolve the shared STT session ID');
+  }
+  requestBody.session_id = sessionId;
+
+  if (options.translationConfig?.source?.[0]) {
+    requestBody.lang = options.translationConfig.source;
+    const sanitizedTargets =
+      options.translationConfig.targets?.filter(
+        target => target !== options.translationConfig?.source[0],
+      ) || [];
+    if (sanitizedTargets.length > 0) {
+      requestBody.translate_config = [
+        {
+          source_lang: options.translationConfig.source[0],
+          target_lang: sanitizedTargets,
+        },
+      ];
+      if (options.method === 'update') {
+        requestBody.translate = true;
+      }
+    } else if (options.method === 'update') {
+      requestBody.translate = false;
+    }
+    requestBody.subscribeAudioUids = [`${options.localUid}`];
+  }
+
+  return requestBody;
+};

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

@@ -0,0 +1,315 @@
+import {type RTMClient} from 'agora-react-native-rtm';
+
+export const STT_SESSION_ID_KEY = 'STT_SESSION_ID';
+
+interface CoordinatorDependencies {
+  getClient: () => Pick<RTMClient, 'storage' | 'presence'>;
+  createId: () => string;
+  wait: (milliseconds: number) => Promise<void>;
+}
+
+export const createSTTSessionCoordinator = (
+  dependencies: CoordinatorDependencies,
+) => {
+  const sessionIds = new Map<string, string>();
+  const pendingResolutions = new Map<string, Promise<string>>();
+
+  const getAndLogChannelMetadata = async (
+    channelName: string,
+    context: string,
+  ) => {
+    const response = await dependencies
+      .getClient()
+      .storage.getChannelMetadata(channelName, 1);
+
+    console.log('[STT_SESSION_ID] Full RTM channel metadata', {
+      channelName,
+      context,
+      metadata: response,
+    });
+
+    return response;
+  };
+
+  const logChannelMetadataBestEffort = async (
+    channelName: string,
+    context: string,
+  ): Promise<void> => {
+    try {
+      await getAndLogChannelMetadata(channelName, context);
+    } catch (error) {
+      console.log('[STT_SESSION_ID] Unable to read RTM channel metadata', {
+        channelName,
+        context,
+        error,
+      });
+    }
+  };
+
+  const readSessionItem = async (channelName: string, context: string) => {
+    const response = await getAndLogChannelMetadata(channelName, context);
+    return response.items?.find(item => item.key === STT_SESSION_ID_KEY);
+  };
+
+  const isOnlyLocalRTMParticipant = async (
+    channelName: string,
+    localUid: string,
+  ): Promise<boolean> => {
+    const response = await dependencies
+      .getClient()
+      .presence.getOnlineUsers(channelName, 1);
+    const occupantUserIds =
+      response.occupants?.map(occupant => String(occupant.userId)) ?? [];
+    const isOnlyLocalParticipant =
+      response.totalOccupancy === 1 &&
+      occupantUserIds.length === 1 &&
+      occupantUserIds[0] === String(localUid);
+
+    console.log('[STT_SESSION_ID] RTM participant check', {
+      channelName,
+      localUid: String(localUid),
+      totalOccupancy: response.totalOccupancy,
+      occupantUserIds,
+      isOnlyLocalParticipant,
+    });
+
+    return isOnlyLocalParticipant;
+  };
+
+  const resolveSessionId = async (channelName: string): Promise<string> => {
+    const delays = [0, 100, 250];
+    let lastError: unknown;
+
+    console.log('[STT_SESSION_ID] Resolving session ID from RTM metadata', {
+      channelName,
+    });
+
+    for (let attempt = 0; attempt < delays.length; attempt += 1) {
+      if (delays[attempt] > 0) {
+        await dependencies.wait(delays[attempt]);
+      }
+
+      try {
+        const existing = await readSessionItem(
+          channelName,
+          `session lookup attempt ${attempt + 1}`,
+        );
+        if (existing?.value) {
+          console.log(
+            '[STT_SESSION_ID] Reusing session ID from RTM channel metadata',
+            {
+              channelName,
+              sessionId: existing.value,
+              revision: existing.revision,
+            },
+          );
+          sessionIds.set(channelName, existing.value);
+          return existing.value;
+        }
+
+        const candidate = dependencies.createId();
+        console.log(
+          '[STT_SESSION_ID] No existing session ID found; creating one',
+          {channelName, sessionId: candidate, attempt: attempt + 1},
+        );
+        try {
+          await dependencies.getClient().storage.setChannelMetadata(
+            channelName,
+            1,
+            {
+              items: [
+                {
+                  key: STT_SESSION_ID_KEY,
+                  value: candidate,
+                  revision: 0,
+                },
+              ],
+            },
+            {addUserId: true, addTimeStamp: true},
+          );
+          console.log(
+            '[STT_SESSION_ID] Created session ID in RTM channel metadata',
+            {channelName, sessionId: candidate},
+          );
+          await logChannelMetadataBestEffort(
+            channelName,
+            'after session ID creation',
+          );
+          sessionIds.set(channelName, candidate);
+          return candidate;
+        } catch (error) {
+          lastError = error;
+          console.log(
+            '[STT_SESSION_ID] Session ID creation did not win; reading shared value',
+            {channelName, sessionId: candidate, error},
+          );
+          const winner = await readSessionItem(
+            channelName,
+            `after creation conflict on attempt ${attempt + 1}`,
+          );
+          if (winner?.value) {
+            console.log(
+              '[STT_SESSION_ID] Reusing session ID created by another participant',
+              {
+                channelName,
+                sessionId: winner.value,
+                revision: winner.revision,
+              },
+            );
+            sessionIds.set(channelName, winner.value);
+            return winner.value;
+          }
+        }
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw new Error(
+      `Unable to resolve the shared STT session ID: ${String(lastError)}`,
+    );
+  };
+
+  const ensureSTTSessionId = async (channelName: string): Promise<string> => {
+    const cached = sessionIds.get(channelName);
+    if (cached) {
+      console.log('[STT_SESSION_ID] Using locally cached session ID', {
+        channelName,
+        sessionId: cached,
+      });
+      return cached;
+    }
+
+    const pending = pendingResolutions.get(channelName);
+    if (pending) {
+      console.log('[STT_SESSION_ID] Waiting for pending session ID lookup', {
+        channelName,
+      });
+      return pending;
+    }
+
+    const resolution = resolveSessionId(channelName);
+    pendingResolutions.set(channelName, resolution);
+    try {
+      return await resolution;
+    } finally {
+      if (pendingResolutions.get(channelName) === resolution) {
+        pendingResolutions.delete(channelName);
+      }
+    }
+  };
+
+  const clearSTTSessionIdIfLast = async (
+    channelName: string,
+    localUid: string,
+  ): Promise<boolean> => {
+    console.log(
+      '[STT_SESSION_ID] Rechecking participants before reading metadata',
+      {channelName, localUid: String(localUid)},
+    );
+    if (!(await isOnlyLocalRTMParticipant(channelName, localUid))) {
+      console.log(
+        '[STT_SESSION_ID] Metadata cleanup skipped because another participant is present',
+        {channelName, localUid: String(localUid)},
+      );
+      return false;
+    }
+
+    const item = await readSessionItem(channelName, 'before metadata removal');
+    if (!item || !item.revision || item.revision <= 0) {
+      console.log(
+        '[STT_SESSION_ID] Metadata cleanup skipped because no removable session ID was found',
+        {channelName},
+      );
+      sessionIds.delete(channelName);
+      pendingResolutions.delete(channelName);
+      return false;
+    }
+
+    console.log(
+      '[STT_SESSION_ID] Final participant check before removing metadata',
+      {channelName, localUid: String(localUid)},
+    );
+    if (!(await isOnlyLocalRTMParticipant(channelName, localUid))) {
+      console.log(
+        '[STT_SESSION_ID] Metadata removal cancelled because a participant joined during cleanup',
+        {channelName, localUid: String(localUid)},
+      );
+      return false;
+    }
+
+    await dependencies
+      .getClient()
+      .storage.removeChannelMetadata(channelName, 1, {
+        data: {
+          items: [
+            {
+              key: STT_SESSION_ID_KEY,
+              value: '',
+              revision: item.revision,
+            },
+          ],
+        },
+        addUserId: true,
+        addTimeStamp: true,
+      });
+    console.log('[STT_SESSION_ID] Removed RTM channel metadata', {
+      channelName,
+      key: STT_SESSION_ID_KEY,
+      revision: item.revision,
+    });
+    sessionIds.delete(channelName);
+    pendingResolutions.delete(channelName);
+    await logChannelMetadataBestEffort(channelName, 'after session ID removal');
+    return true;
+  };
+
+  const cleanupSTTSessionOnEnd = async (
+    channelName: string,
+    localUid: string,
+    isSTTActive: boolean,
+    stopSTT: () => Promise<void>,
+  ): Promise<void> => {
+    console.log(
+      '[STT_SESSION_ID] Checking participants before starting end-call cleanup',
+      {channelName, localUid: String(localUid), isSTTActive},
+    );
+    if (!(await isOnlyLocalRTMParticipant(channelName, localUid))) {
+      console.log(
+        '[STT_SESSION_ID] End-call cleanup skipped because another participant is present',
+        {channelName, localUid: String(localUid)},
+      );
+      return;
+    }
+    if (isSTTActive) {
+      console.log(
+        '[STT_SESSION_ID] Local user is last; stopping STT before metadata cleanup',
+        {channelName},
+      );
+      await stopSTT();
+    }
+    console.log(
+      '[STT_SESSION_ID] STT stop completed; revalidating before metadata cleanup',
+      {channelName},
+    );
+    await clearSTTSessionIdIfLast(channelName, localUid);
+  };
+
+  const resetSTTSessionIdCache = (channelName?: string): void => {
+    if (channelName) {
+      sessionIds.delete(channelName);
+      pendingResolutions.delete(channelName);
+      return;
+    }
+    sessionIds.clear();
+    pendingResolutions.clear();
+  };
+
+  return {
+    ensureSTTSessionId,
+    isOnlyLocalRTMParticipant,
+    clearSTTSessionIdIfLast,
+    cleanupSTTSessionOnEnd,
+    resetSTTSessionIdCache,
+  };
+};

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

@@ -0,0 +1,21 @@
+import RTMEngine from '../../rtm/RTMEngine';
+import getUniqueID from '../../utils/getUniqueID';
+import {createSTTSessionCoordinator} from './sttSessionCoordinator';
+
+export {
+  createSTTSessionCoordinator,
+  STT_SESSION_ID_KEY,
+} from './sttSessionCoordinator';
+
+const coordinator = createSTTSessionCoordinator({
+  getClient: () => RTMEngine.getInstance().engine,
+  createId: getUniqueID,
+  wait: milliseconds =>
+    new Promise(resolve => setTimeout(resolve, milliseconds)),
+});
+
+export const ensureSTTSessionId = coordinator.ensureSTTSessionId;
+export const isOnlyLocalRTMParticipant = coordinator.isOnlyLocalRTMParticipant;
+export const clearSTTSessionIdIfLast = coordinator.clearSTTSessionIdIfLast;
+export const cleanupSTTSessionOnEnd = coordinator.cleanupSTTSessionOnEnd;
+export const resetSTTSessionIdCache = coordinator.resetSTTSessionIdCache;