fcr-core 3.8.1 → 3.9.0-alpha

package/lib-es/service/type.js

@@ -0,0 +1 @@
+export {};

package/lib-es/type.js

@@ -0,0 +1,222 @@
+// 基础导入类型（集中管理第三方依赖类型别名）
+
+// 内部枚举与基础类型导入
+
+import { FcrUserRole } from './room-control/user-control/type';
+
+// 模块类型导出（按功能模块分组）
+// 聊天连接模块
+
+import { getRtcPresetParameters } from './utilities/parameters';
+
+// 第三方类型别名（统一前缀避免冲突）
+export { AgoraRtcAiDenoiseLevel as FcrAiDenoiseLevel, AgoraRtcAudioSourceType as FcrAudioSourceType, AgoraRtcCapability as FcrCapability, AgoraRteConnectionState as FcrConnectionState, AgoraRtcMediaSourceState as FcrMediaSourceState, AgoraRteRegion as FcrRegion, AgoraRteRoomConnectorType as FcrRoomConnectorType, AgoraRteScreenCaptureType as FcrScreenCaptureType, AgoraRteLatencyLevel as FcrStreamLatencyLevel, AgoraRteStreamPrivilegeAudioSourceType as FcrStreamPrivilegeAudioSourceType, AgoraRteStreamPrivilegeOperation as FcrStreamPrivilegeOperation, AgoraRteStreamPrivilegeVideoSourceType as FcrStreamPrivilegeVideoSourceType, AgoraRteMediaStreamType as FcrStreamType, AgoraRteUserUpdatedReason as FcrUserUpdatedReason, AgoraRteVideoOrientation as FcrVideoOrientation, AgoraRtcRenderMode as FcrVideoRenderMode, AgoraRtcVideoSourceType as FcrVideoSourceType, AgoraRtcVideoStreamType as FcrVideoStreamType, registerPlugin } from './imports';
+import { FcrDualVideoStreamConfig } from './utilities/dual-video-stream-config';
+import { FcrVideoEncoderConfig } from './utilities/video-encoder-config';
+// 基础类型别名（简化常用类型引用）
+export { FcrDualVideoStreamConfig };
+
+// 媒体控制模块
+
+// 监控控制模块
+
+// 点对点会话模块
+
+// 房间控制模块 - 能力控制
+export { FcrAbility } from './room-control/ability-control/type';
+// 房间控制模块 - 聊天室控制
+export { FcrChatRoomConnectionState, FcrChatRoomMessageType } from './room-control/chatroom-control/type';
+// 房间控制模块 - 翻译控制
+export { FcrInterpreterActionType, FcrLanguage } from './room-control/interpreter-control/types';
+
+// 房间控制模块 - 权限控制
+
+export { FcrChatPermissionType, FcrOperatePermissionType, FcrPermissionAction, FcrPrivilegeUserRole, FcrPrivilegeUserRoleToStringMap, FcrPrivilegeUserStringToRoleMap, FcrSecurityAction, FcrWatermarkPermissionState } from './room-control/privilege-control/type';
+
+// 房间控制模块 - 连接器控制
+export { FcrIPConnectorSessionType, FcrRoomConnectorPhoneRegion, FcrRoomConnectorSessionReason, FcrRoomConnectorSessionState } from './room-control/room-connector-control/type';
+
+// 房间控制模块 - 房间会话
+
+// 房间控制模块 - 共享控制
+export { FcrScreenSharingState, FcrWhiteboardState } from './room-control/sharing-control/type';
+
+// 房间控制模块 - 流控制
+
+// 房间控制模块 - 用户控制
+export { FcrUserKickedOutType, FcrUserLeftReason, FcrUserRole } from './room-control/user-control/type';
+
+// 房间控制模块 - 白板标注控制
+
+// 房间控制模块 - 白板控制
+
+// 房间路由模块
+
+// 服务相关类型
+
+export { FcrVideoEncoderConfig };
+
+// 核心引擎类型扩展
+
+// 房间相关核心类型
+export let FcrRoomState = /*#__PURE__*/function (FcrRoomState) {
+  FcrRoomState[FcrRoomState["Initialized"] = 0] = "Initialized";
+  FcrRoomState[FcrRoomState["Started"] = 1] = "Started";
+  FcrRoomState[FcrRoomState["Ended"] = 2] = "Ended";
+  FcrRoomState[FcrRoomState["Closed"] = 3] = "Closed";
+  return FcrRoomState;
+}({});
+export let FcrRecordingState = /*#__PURE__*/function (FcrRecordingState) {
+  FcrRecordingState[FcrRecordingState["Starting"] = 1] = "Starting";
+  FcrRecordingState[FcrRecordingState["Started"] = 2] = "Started";
+  FcrRecordingState[FcrRecordingState["Paused"] = 3] = "Paused";
+  FcrRecordingState[FcrRecordingState["Stopped"] = 4] = "Stopped";
+  return FcrRecordingState;
+}({});
+
+/** 房间基本信息 */
+
+/** 平台类型枚举 */
+export let FcrPlatform = /*#__PURE__*/function (FcrPlatform) {
+  FcrPlatform[FcrPlatform["UNSUPPORTED"] = -1] = "UNSUPPORTED";
+  FcrPlatform[FcrPlatform["WEB_DESKTOP"] = 1] = "WEB_DESKTOP";
+  FcrPlatform[FcrPlatform["MACOS"] = 2] = "MACOS";
+  FcrPlatform[FcrPlatform["WINDOWS"] = 3] = "WINDOWS";
+  FcrPlatform[FcrPlatform["IOS"] = 4] = "IOS";
+  FcrPlatform[FcrPlatform["ANDROID"] = 5] = "ANDROID";
+  FcrPlatform[FcrPlatform["WEB_MOBILE"] = 6] = "WEB_MOBILE";
+  FcrPlatform[FcrPlatform["HARMONY"] = 7] = "HARMONY";
+  FcrPlatform[FcrPlatform["CONNECTOR_PSTN"] = 101] = "CONNECTOR_PSTN";
+  FcrPlatform[FcrPlatform["CONNECTOR_SIP"] = 102] = "CONNECTOR_SIP";
+  FcrPlatform[FcrPlatform["CONNECTOR_H323"] = 103] = "CONNECTOR_H323";
+  return FcrPlatform;
+}({});
+
+/** 用户信息类型 */
+
+/** 流信息类型 */
+
+/** 房间日程安排 */
+
+/** 录制信息 */
+
+// 群组相关类型
+
+// 群组事件类型（统一事件格式）
+
+// 房间路由事件
+
+// 会话相关类型
+
+// 媒体设备相关类型
+
+// 性能与网络相关类型
+
+// 云端录制配置
+export let FcrCloudRecordingAudioProfile = /*#__PURE__*/function (FcrCloudRecordingAudioProfile) {
+  FcrCloudRecordingAudioProfile[FcrCloudRecordingAudioProfile["DEFAULT"] = 0] = "DEFAULT";
+  // mono 单声道 48khz 48kbps
+  FcrCloudRecordingAudioProfile[FcrCloudRecordingAudioProfile["MONO_48KHZ_128KBPS"] = 1] = "MONO_48KHZ_128KBPS";
+  // mono 单声道 48khz 128kbps
+  FcrCloudRecordingAudioProfile[FcrCloudRecordingAudioProfile["STEREO_48KHZ_192KBPS"] = 2] = "STEREO_48KHZ_192KBPS"; // stereo 立体声 48khz 192kbps
+  return FcrCloudRecordingAudioProfile;
+}({});
+export const FcrUserRoleToStringMap = {
+  [FcrUserRole.HOST]: 'host',
+  [FcrUserRole.COHOST]: 'cohost',
+  [FcrUserRole.PARTICIPANT]: 'participant',
+  [FcrUserRole.AUDIENCE]: 'audience',
+  [FcrUserRole.OBSERVER]: 'observer',
+  [FcrUserRole.ROBOT]: 'robot'
+};
+export const FcrUserStringToRoleMap = {
+  host: FcrUserRole.HOST,
+  cohost: FcrUserRole.COHOST,
+  participant: FcrUserRole.PARTICIPANT,
+  audience: FcrUserRole.AUDIENCE,
+  observer: FcrUserRole.OBSERVER,
+  robot: FcrUserRole.ROBOT
+};
+export let FcrReturnCode = /*#__PURE__*/function (FcrReturnCode) {
+  FcrReturnCode[FcrReturnCode["UNDEFINED"] = -1] = "UNDEFINED";
+  FcrReturnCode[FcrReturnCode["SUCCESS"] = 0] = "SUCCESS";
+  return FcrReturnCode;
+}({});
+
+// 直播相关类型
+export let FcrLiveStreamingLayoutType = /*#__PURE__*/function (FcrLiveStreamingLayoutType) {
+  FcrLiveStreamingLayoutType[FcrLiveStreamingLayoutType["GALLERY"] = 1] = "GALLERY";
+  // 画廊模式
+  FcrLiveStreamingLayoutType[FcrLiveStreamingLayoutType["SPEAKER"] = 2] = "SPEAKER"; // 主讲模式
+  return FcrLiveStreamingLayoutType;
+}({});
+export let FcrLiveStreamingState = /*#__PURE__*/function (FcrLiveStreamingState) {
+  FcrLiveStreamingState[FcrLiveStreamingState["STARTING"] = 1] = "STARTING";
+  FcrLiveStreamingState[FcrLiveStreamingState["STARTED"] = 2] = "STARTED";
+  FcrLiveStreamingState[FcrLiveStreamingState["STOPPED"] = 3] = "STOPPED";
+  return FcrLiveStreamingState;
+}({});
+export let RoomMessageKey = /*#__PURE__*/function (RoomMessageKey) {
+  RoomMessageKey["USER_WAITING_ROOM_JOINED"] = "USER_WAITING_ROOM_JOINED";
+  return RoomMessageKey;
+}({});
+export { FcrDeviceType } from './media-control/type';
+export { FcrLineType } from './room-control/type';
+export { FcrError } from './utilities/error';
+export let FcrStreamState = /*#__PURE__*/function (FcrStreamState) {
+  FcrStreamState[FcrStreamState["UNPUBLISH"] = 0] = "UNPUBLISH";
+  FcrStreamState[FcrStreamState["PUBLISH"] = 1] = "PUBLISH";
+  return FcrStreamState;
+}({});
+export { FcrBoardShape, FcrBoardToolType } from './room-control/whiteboard-control-v2/enum';
+/** 引擎配置类 */
+export class FcrCoreEngineConfig {
+  /** 应用唯一标识 */
+
+  /** 身份验证令牌 */
+
+  /** 用户唯一标识 */
+
+  /** 服务区域 */
+
+  /** 双摄像头视频流配置 */
+
+  /** 双屏幕视频流配置 */
+
+  /** 额外参数配置 */
+
+  constructor(params) {
+    this.appId = params.appId;
+    this.token = params.token;
+    this.userId = params.userId;
+    this.region = params.region;
+    this.dualCameraVideoStreamConfig = params.dualCameraVideoStreamConfig;
+    this.dualScreenVideoStreamConfig = params.dualScreenVideoStreamConfig;
+    this.parameters = params.parameters;
+    this._prependInternalParameters();
+  }
+  static createDefaultConfig(appId, token, region, userId, parameters) {
+    return new FcrCoreEngineConfig({
+      appId,
+      token,
+      userId,
+      region,
+      dualCameraVideoStreamConfig: FcrDualVideoStreamConfig.createDefaultCameraConfig(),
+      dualScreenVideoStreamConfig: FcrDualVideoStreamConfig.createDefaultScreenConfig(),
+      parameters
+    });
+  }
+  _prependInternalParameters() {
+    const rtcPresetParameters = getRtcPresetParameters();
+    if (!this.parameters) {
+      this.parameters = {
+        rtc: rtcPresetParameters
+      };
+    } else if (!this.parameters.rtc) {
+      this.parameters.rtc = rtcPresetParameters;
+    } else {
+      // 将内部参数插入到数组前列
+      this.parameters.rtc.unshift(...rtcPresetParameters);
+    }
+  }
+}

package/lib-es/utilities/abortable-retry.js

@@ -0,0 +1,54 @@
+import "core-js/modules/web.dom-exception.stack.js";
+import { retryAttempt, to } from '../imports';
+/**
+ * Creates an abortable retry operation that can be cancelled at any time.
+ *
+ * The handler function will be retried up to `retriesMax` times if it fails.
+ * The operation can be cancelled by calling the returned abort function,
+ * which will cause the promise to reject with an AbortError.
+ *
+ * @example
+ * ```typescript
+ * const [abort, promise] = abortableRetry(async (signal) => {
+ *   await asyncFunction1();
+ *   // Check if aborted after each async operation
+ *   signal.throwIfAborted();
+ *
+ *   await asyncFunction2();
+ *   signal.throwIfAborted();
+ *
+ *   return result;
+ * }, { retriesMax: 10 });
+ *
+ * // Cancel the operation at any time
+ * setTimeout(() => abort(), 5000);
+ *
+ * const [err, result] = await promise;
+ * if (err?.name === 'AbortError') {
+ *   console.log('Operation was cancelled');
+ * }
+ * ```
+ *
+ * @param handler - Async function that receives an AbortSignal.
+ *                  Should call `signal.throwIfAborted()` periodically to check for cancellation.
+ * @param options - Retry configuration
+ * @returns Tuple of [abort function, result promise]. The promise resolves to [error, result].
+ */
+export const abortableRetry = (handler, options) => {
+  const abortController = new AbortController();
+  const promise = to(retryAttempt(async () => {
+    abortController.signal.throwIfAborted();
+    const result = await handler(abortController.signal);
+    abortController.signal.throwIfAborted();
+    return result;
+  }, [], {
+    retriesMax: options.retriesMax
+  }).fail(async options => {
+    if (abortController.signal.aborted) {
+      throw new DOMException('Operation aborted', 'AbortError');
+    }
+    await options.timeFn();
+    return true;
+  }).exec());
+  return [() => abortController.abort(), promise];
+};

package/lib-es/utilities/cmd.js

@@ -0,0 +1 @@
+export const CMD_PEER_MESSAGE = 101;

package/lib-es/utilities/collection.js

@@ -0,0 +1,64 @@
+import "core-js/modules/es.array.push.js";
+export const iterateMap = (map, processors) => {
+  const onFilter = processors?.onFilter || (() => true);
+  const {
+    onMap,
+    onReduce
+  } = processors || {};
+  const list = [];
+  let prev = undefined;
+  for (const [k, v] of map.entries()) {
+    if (onFilter(k, v)) {
+      if (onMap) list.push(onMap(k, v));
+      if (onReduce) prev = onReduce(prev, k, v);
+    }
+  }
+  return {
+    list,
+    prev
+  };
+};
+export const iterateSet = (map, processors) => {
+  const onFilter = processors?.onFilter || (() => true);
+  const {
+    onMap,
+    onReduce
+  } = processors || {};
+  const list = [];
+  let prev = undefined;
+  for (const item of map.values()) {
+    if (onFilter(item)) {
+      if (onMap) list.push(onMap(item));
+      if (onReduce) prev = onReduce(prev, item);
+    }
+  }
+  return {
+    list,
+    prev
+  };
+};
+
+/**
+ * expand a key-value map to a structure
+ * .e.g. { 'a.b.c': 1 } => { a: { b: { c: 1 } } }
+ * @param kvMap
+ */
+export const convertToStructure = kvMap => {
+  const result = {};
+  for (const key in kvMap) {
+    const keys = key.split('.');
+    let temp = result;
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      if (i === keys.length - 1) {
+        temp[k] = kvMap[key];
+      } else {
+        if (!temp[k]) {
+          temp[k] = {};
+        }
+        temp = temp[k];
+      }
+    }
+  }
+  return result;
+};

package/lib-es/utilities/dual-video-stream-config.js

@@ -0,0 +1,19 @@
+import { FcrVideoEncoderConfig } from './video-encoder-config';
+export let FcrDualVideoStreamConfig;
+(function (_FcrDualVideoStreamConfig) {
+  function createDefaultCameraConfig() {
+    return {
+      highVideoEncoderConfig: FcrVideoEncoderConfig.createDefaultHighCameraConfig(),
+      lowVideoEncoderConfig: FcrVideoEncoderConfig.createDefaultLowCameraConfig(),
+      enableDualStreamMode: true
+    };
+  }
+  _FcrDualVideoStreamConfig.createDefaultCameraConfig = createDefaultCameraConfig;
+  function createDefaultScreenConfig() {
+    return {
+      highVideoEncoderConfig: FcrVideoEncoderConfig.createDefaultClarityScreenConfig(),
+      enableDualStreamMode: false
+    };
+  }
+  _FcrDualVideoStreamConfig.createDefaultScreenConfig = createDefaultScreenConfig;
+})(FcrDualVideoStreamConfig || (FcrDualVideoStreamConfig = {}));

package/lib-es/utilities/error-helpers.js

@@ -0,0 +1,224 @@
+/**
+ * 通用错误处理辅助工具
+ *
+ * 提供统一的错误创建和处理机制，支持实例化配置
+ */
+
+import { DetailErrorCode, ErrorModuleCode } from '../imports';
+import { generateFcrCoreClientError } from './error';
+
+/**
+ * 控制器类型枚举
+ */
+export let ControllerType = /*#__PURE__*/function (ControllerType) {
+  ControllerType["USER"] = "user";
+  ControllerType["STREAM"] = "stream";
+  ControllerType["ROOM_SESSION"] = "room session";
+  ControllerType["CHAT_ROOM"] = "chat room";
+  ControllerType["PRIVILEGE"] = "privilege";
+  ControllerType["ROOM_CONNECTOR"] = "room connector";
+  ControllerType["ABILITY"] = "ability";
+  ControllerType["SHARING"] = "sharing";
+  ControllerType["WHITEBOARD"] = "whiteboard";
+  ControllerType["MONITOR"] = "monitor";
+  ControllerType["MEDIA"] = "media";
+  ControllerType["STT"] = "stt";
+  return ControllerType;
+}({});
+
+/**
+ * 错误处理配置接口
+ */
+
+/**
+ * 错误处理助手类 - 支持实例化配置
+ */
+export class FcrErrorHelper {
+  constructor(config = {}) {
+    this.config = {
+      defaultModuleCode: ErrorModuleCode.FCR_ROOM,
+      enableDetailedMessages: true,
+      logPrefix: 'FCR',
+      autoLog: false,
+      ...config
+    };
+  }
+  /**
+   * 生成控制器未初始化错误
+   * @param controllerType 控制器类型
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createControllerNotInitializedError(controllerType, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] The ${controllerType} controller is not initialized, please join the room first` : `${controllerType} controller not initialized`;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.NOT_JOINED_ROOM, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`);
+    }
+    return error;
+  }
+
+  /**
+   * 生成操作冲突错误
+   * @param operation 操作名称
+   * @param reason 冲突原因
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createOperationConflictError(operation, reason, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] Failed to ${operation}: ${reason}` : `${operation} failed: ${reason}`;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.JOIN_CONFLICT, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`);
+    }
+    return error;
+  }
+
+  /**
+   * 生成操作取消错误
+   * @param operation 操作名称
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createOperationCanceledError(operation, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] ${operation} operation has been cancelled` : `${operation} cancelled`;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.NOT_JOINED_ROOM, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`);
+    }
+    return error;
+  }
+
+  /**
+   * 生成消息发送错误
+   * @param originalError 原始错误
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createSendMessageError(originalError, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] Send message failed: ${originalError.message}` : 'send message failed';
+    const error = generateFcrCoreClientError(module, DetailErrorCode.UNDEFINED_ERROR, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`, originalError);
+    }
+    return error;
+  }
+
+  /**
+   * 生成通用操作错误
+   * @param operation 操作类型
+   * @param originalError 原始错误
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createOperationError(operation, originalError, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] ${operation} failed${originalError ? `: ${originalError.message}` : ''}` : `${operation} failed`;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.NOT_JOINED_ROOM, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`, originalError);
+    }
+    return error;
+  }
+
+  /**
+   * 生成网络请求相关错误
+   * @param message 错误消息
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createNetworkError(message, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const formattedMessage = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] Network error: ${message}` : message;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.LOCAL_HTTP_REQUEST_FAILED, formattedMessage);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${formattedMessage}`);
+    }
+    return error;
+  }
+
+  /**
+   * 生成参数无效错误
+   * @param paramName 参数名
+   * @param reason 无效原因
+   * @param moduleCode 模块错误码
+   * @returns FcrError
+   */
+  createInvalidParamsError(paramName, reason, moduleCode) {
+    const module = moduleCode ?? this.config.defaultModuleCode;
+    const message = this.config.enableDetailedMessages ? `[${this.config.logPrefix}] Invalid parameter '${paramName}': ${reason}` : `Invalid parameter '${paramName}': ${reason}`;
+    const error = generateFcrCoreClientError(module, DetailErrorCode.INVALID_PARAMS, message);
+    if (this.config.autoLog) {
+      console.error(`${this.config.logPrefix}: ${message}`);
+    }
+    return error;
+  }
+
+  /**
+   * 生成房间加入冲突错误的便捷方法
+   */
+  createJoinConflictError(isAlreadyJoined) {
+    const reason = isAlreadyJoined ? 'the room has been joined' : 'the previous join operation is not completed';
+    return this.createOperationConflictError('join the room', reason);
+  }
+
+  /**
+   * 静态工厂方法 - 创建默认实例
+   */
+  static createDefault() {
+    return new FcrErrorHelper();
+  }
+
+  /**
+   * 为房间控制创建专用实例
+   */
+  static forRoomControl() {
+    return new FcrErrorHelper({
+      defaultModuleCode: ErrorModuleCode.FCR_ROOM,
+      logPrefix: 'RoomControl',
+      enableDetailedMessages: true
+    });
+  }
+
+  /**
+   * 为引擎创建专用实例
+   */
+  static forEngine() {
+    return new FcrErrorHelper({
+      defaultModuleCode: ErrorModuleCode.FCR_ENGINE,
+      logPrefix: 'Engine',
+      enableDetailedMessages: true
+    });
+  }
+
+  /**
+   * 为直播创建专用实例
+   */
+  static forLiveStreaming() {
+    return new FcrErrorHelper({
+      defaultModuleCode: ErrorModuleCode.FCR_ROOM_LIVE_STREAMING,
+      logPrefix: 'LiveStreaming',
+      enableDetailedMessages: true
+    });
+  }
+}
+
+/**
+ * 预配置的错误处理器实例
+ */
+
+// 默认实例 - 用于通用错误处理
+export const defaultErrorHelper = FcrErrorHelper.createDefault();
+
+// 房间控制专用实例 - 用于房间相关错误
+export const roomControlErrorHelper = FcrErrorHelper.forRoomControl();
+
+// 引擎专用实例 - 用于引擎相关错误
+export const engineErrorHelper = FcrErrorHelper.forEngine();
+
+// 直播专用实例 - 用于直播相关错误
+export const liveStreamingErrorHelper = FcrErrorHelper.forLiveStreaming();

package/lib-es/utilities/error.js

@@ -0,0 +1,43 @@
+import { DetailErrorCode, ErrorServiceType } from '../imports';
+import { padStart, AgoraRestfulClientError, FcrError } from '../imports';
+export { FcrError } from '../imports';
+
+// Export aliases for compatibility
+export { DetailErrorCode as FcrErrorCode, ErrorModuleCode as FcrErrorModuleCode } from '../imports';
+
+// helpers
+export const generateFcrCoreClientError = (module, code, message, origin) => {
+  return FcrError.create(ErrorServiceType.FCR_CLIENT, module, code, message, origin);
+};
+export const generateFcrCoreServerError = (code, message, origin) => {
+  const errorCode = Number(`${ErrorServiceType.FCR_SERVER}${padStart(String(code), 8, '0')}`);
+  const error = new FcrError({
+    message: message,
+    code: errorCode
+  });
+  return error;
+};
+
+// TODO: i don't know
+export const handleRequestError = async (action, errorModuleCode, errorMessage) => {
+  try {
+    return await action();
+  } catch (e) {
+    if (e instanceof AgoraRestfulClientError) {
+      throw generateFcrCoreServerError(e.serviceCode ?? -1, e.message, e);
+    }
+    const error = e;
+    throw generateFcrCoreClientError(errorModuleCode, DetailErrorCode.UNDEFINED_ERROR, errorMessage ?? error.message, error);
+  }
+};
+
+// 720410100 // 房间已销毁
+// 720404100 // 房间不存在
+// 732403100 // 无加入权限，如：房间已锁定
+// 732403101 // 房间不存在或密码错误
+// 100050051 // ap 探测失败
+// 300000010 // 加入rtc频道超时了（rtc私有化）
+// 400000010 // 加入web rtc频道超时了（rtc私有化）
+// 730403100 // 被永久踢出房间
+// error codes that cannot be retried when joining a room
+export const ERROR_CODES_NOT_RETRYABLE_WHEN_JOINING_ROOM = [720410100, 720404100, 732403100, 732403101, 100050051, 300000010, 400000010, 730403100];