@ohos-ports/agora-rtc-sdk-ng 4.24.8-beta.0

package/README-zh_CN.md

@@ -0,0 +1,65 @@
+# AgoraRTC SDK (Version 4.x)
+
+[English](./README.md) | 简体中文
+
+## 开始
+
+### 安装
+
+使用 `npm`, `pnpm` 或 `yarn`
+
+```bash
+# 使用 npm
+npm i agora-rtc-sdk-ng
+# 或者使用 pnpm
+pnpm add agora-rtc-sdk-ng
+# 或者使用 yarn
+yarn add agora-rtc-sdk-ng
+```
+
+我们也提供了 CDN。SDK 会在全局导出 `AgoraRTC`。
+
+```html
+<!-- 默认 UMD，不含 AI QoS -->
+<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.24.8.js"></script>
+```
+
+CDN 使用 AI QoS 时只引入 full 包，AI 已注册，不必再挂扩展脚本：
+
+```html
+<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.24.8-full.js"></script>
+<script>
+  const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+  await client.join(appId, channel, token, uid);
+</script>
+```
+
+npm 的 UMD 同样拆分。默认入口不含 AI QoS；完整包走 `agora-rtc-sdk-ng/full`：
+
+```javascript
+import AgoraRTC from "agora-rtc-sdk-ng/full";
+
+const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+await client.join(appId, channel, token, uid);
+```
+
+ESM 逻辑不变：主 ESM + 可选 service：
+
+```javascript
+import AgoraRTC from "agora-rtc-sdk-ng/esm";
+import { AiAudioModeService } from "agora-rtc-sdk-ng/services/ai-audio-mode";
+
+AgoraRTC.use(AiAudioModeService);
+const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+await client.join(appId, channel, token, uid);
+```
+
+### 快速开始
+
+我们提供了 `React`, `Vue`, `Svelte` 的 Demo, 访问地址 [Quick Start Demo](https://github.com/AgoraIO/agora-rtc-web/blob/main/projects).
+
+详细可参考文档 [api-ref.agora.io](https://doc.shengwang.cn/api-ref/rtc/javascript/overview).
+
+## 变更记录
+
+变更记录访问地址为 [Release Notes](https://doc.shengwang.cn/doc/rtc/javascript/overview/release-notes).

package/README.md

@@ -0,0 +1,66 @@
+# AgoraRTC SDK (Version 4.x)
+
+English | [简体中文](https://github.com/AgoraIO/agora-rtc-web/blob/main/README-zh_CN.md)
+
+## Getting Started
+
+### Install
+
+Use `npm`, `pnpm` or `yarn`
+
+```bash
+# with npm
+npm i agora-rtc-sdk-ng
+# or with pnpm
+pnpm add agora-rtc-sdk-ng
+# or with yarn
+yarn add agora-rtc-sdk-ng
+```
+
+CDN is also provided. The SDK exports a global `AgoraRTC` object.
+
+```html
+<!-- default UMD, no AI QoS -->
+<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.24.8.js"></script>
+```
+
+To use AI QoS from CDN, load the full UMD instead. AI is already registered; only this one script is needed:
+
+```html
+<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.24.8-full.js"></script>
+<script>
+  const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+  await client.join(appId, channel, token, uid);
+</script>
+```
+
+npm UMD is the same split. Default has no AI QoS; `agora-rtc-sdk-ng/full` is the complete build:
+
+```javascript
+import AgoraRTC from "agora-rtc-sdk-ng/full";
+
+const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+await client.join(appId, channel, token, uid);
+```
+
+ESM is unchanged: import the main ESM, then the optional service:
+
+```javascript
+import AgoraRTC from "agora-rtc-sdk-ng/esm";
+import { AiAudioModeService } from "agora-rtc-sdk-ng/services/ai-audio-mode";
+
+AgoraRTC.use(AiAudioModeService);
+const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", aiClientMode: true });
+await client.join(appId, channel, token, uid);
+```
+
+### Quick start
+
+`React`, `Vue`, `Svelte` quick start demo are provided, please check at [Quick Start Demo](https://github.com/AgoraIO/agora-rtc-web/blob/main/projects).
+We also have [More Demos](https://github.com/AgoraIO/API-Examples-Web/tree/main/Demo).
+
+Please follow the documentation at [api-ref.agora.io](https://api-ref.agora.io/en/voice-sdk/web/4.x/index.html).
+
+## Changelogs
+
+Please check the changelogs at [Release Notes](https://docs.agora.io/en/video-calling/overview/release-notes?platform=web).

package/browser-shim.cjs

@@ -0,0 +1,424 @@
+/**
+ * browser-shim.cjs — HarmonyOS / Node.js browser-runtime shim for agora-rtc-sdk-ng.
+ *
+ * The Agora WebRTC SDK is authored for browsers: its UMD bundle dereferences
+ * `window` at module top level and its APIs expect browser globals
+ * (window, navigator, document, location, ...).
+ *
+ * Strategy (in order):
+ *  1. Browser/bundler environment (window already defined) → no-op.
+ *  2. jsdom available (declared as optionalDependency) → provision a real
+ *     browser DOM environment. jsdom is a genuine DOM implementation — it is
+ *     NOT a stub of the SDK's functionality. Preferred path.
+ *  3. jsdom unavailable (e.g. npm did not install optionalDependencies of a
+ *     file: dependency) → minimal platform-adaptation layer that provides
+ *     only the global object structure the UMD bundle needs to load. It does
+ *     NOT fake any RTC capability.
+ *
+ * Scope / limitations (documented honestly):
+ *  - Provided: window, document, navigator, location, DOM element classes.
+ *  - NOT provided (deliberately, no verified implementation exists):
+ *      * RTCPeerConnection / RTCDataChannel — no W3C-compatible WebRTC
+ *        implementation is available for Node.js on HarmonyOS
+ *        (@ohos-ports/node-datachannel exposes only libdatachannel's
+ *        low-level PeerConnection API, not the W3C surface).
+ *      * navigator.mediaDevices — camera/microphone capture is a browser
+ *        capability.
+ *      * W3C WebSocket signaling to Agora SD-RTN.
+ *    RTC-dependent APIs report NOT_SUPPORTED at runtime.
+ */
+
+function noop() {}
+
+function createEventTargetShim(target) {
+  const listeners = new Map();
+  target.addEventListener = function (type, fn) {
+    if (!listeners.has(type)) listeners.set(type, new Set());
+    listeners.get(type).add(fn);
+  };
+  target.removeEventListener = function (type, fn) {
+    if (listeners.has(type)) listeners.get(type).delete(fn);
+  };
+  target.dispatchEvent = function (event) {
+    const set = listeners.get(event && event.type);
+    if (set) for (const fn of Array.from(set)) fn(event);
+    return true;
+  };
+  return target;
+}
+
+function createElementShim() {
+  return createEventTargetShim({
+    style: {},
+    children: [],
+    classList: { add: noop, remove: noop, toggle: noop },
+    setAttribute: noop,
+    getAttribute: () => null,
+    appendChild(child) { this.children.push(child); return child; },
+    removeChild: noop,
+    getContext: () => null,
+  });
+}
+
+/**
+ * Minimal platform-adaptation layer: enough global object structure for the
+ * UMD bundle to load under Node.js. Provides NO RTC capability.
+ */
+function applyMinimalShim() {
+  createEventTargetShim(globalThis);
+  if (typeof globalThis.window === "undefined") globalThis.window = globalThis;
+  if (typeof globalThis.self === "undefined") globalThis.self = globalThis;
+
+  if (typeof globalThis.location === "undefined") {
+    globalThis.location = {
+      href: "https://localhost:8080/",
+      origin: "https://localhost:8080",
+      protocol: "https:",
+      host: "localhost:8080",
+      hostname: "localhost",
+      port: "8080",
+      pathname: "/",
+      search: "",
+      hash: "",
+      toString() { return this.href; },
+    };
+  }
+
+  if (typeof globalThis.document === "undefined") {
+    globalThis.document = createEventTargetShim({
+      createElement: createElementShim,
+      createElementNS: createElementShim,
+      createTextNode: () => ({}),
+      documentElement: createEventTargetShim({ style: {} }),
+      head: createEventTargetShim({ appendChild: noop }),
+      body: createEventTargetShim({ appendChild: noop }),
+      getElementById: () => null,
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      visibilityState: "visible",
+      hidden: false,
+    });
+  }
+
+  // DOM element/media type classes used for instanceof-style checks.
+  const classNames = [
+    "HTMLElement", "HTMLVideoElement", "HTMLAudioElement", "HTMLCanvasElement",
+    "HTMLDivElement", "HTMLImageElement", "HTMLIFrameElement", "HTMLScriptElement",
+    "MediaStream", "MediaStreamTrack", "MediaRecorder",
+    "Blob", "File", "FileReader", "FormData", "XMLHttpRequest",
+    "CustomEvent", "Event", "EventTarget",
+    "MessageChannel", "Worker",
+    "MutationObserver", "ResizeObserver", "IntersectionObserver", "PerformanceObserver",
+    "AudioContext", "AudioBuffer", "GainNode",
+    "MediaStreamAudioSourceNode", "MediaStreamAudioDestinationNode",
+    "ScreenOrientation", "ClipboardItem", "DOMException",
+  ];
+  for (const name of classNames) {
+    if (typeof globalThis[name] === "undefined") {
+      globalThis[name] = class ShimClass {
+        constructor() { this.style = {}; }
+      };
+    }
+  }
+  // AudioContext needs a minimal real-ish surface used during construction.
+  if (typeof globalThis.AudioContext === "function") {
+    const AC = globalThis.AudioContext;
+    if (!AC.prototype.createGain) {
+      AC.prototype.createGain = function () {
+        return {
+          gain: { value: 1, setValueAtTime: noop, linearRampToValueAtTime: noop },
+          connect: () => ({}), disconnect: noop,
+        };
+      };
+      AC.prototype.createMediaStreamSource = function () { return { connect: () => ({}) }; };
+      AC.prototype.createMediaStreamDestination = function () {
+        return { connect: noop, stream: { getTracks: () => [], getAudioTracks: () => [] } };
+      };
+      AC.prototype.decodeAudioData = function () { return Promise.reject(new Error("decodeAudioData: not supported in Node.js shim")); };
+      AC.prototype.resume = () => Promise.resolve();
+      AC.prototype.close = () => Promise.resolve();
+    }
+  }
+  return true;
+}
+
+function applyJSDomShim() {
+  const { JSDOM } = require("jsdom");
+
+  const dom = new JSDOM("<!doctype html><html><head></head><body></body></html>", {
+    url: "https://localhost:8080/",
+    pretendToBeVisual: true,
+  });
+
+  const g = globalThis;
+  const w = dom.window;
+
+  if (!g.window) g.window = w;
+  if (!g.document) g.document = w.document;
+  if (!g.navigator) g.navigator = w.navigator;
+  if (!g.location) g.location = w.location;
+  if (!g.self) g.self = w;
+  if (!g.HTMLElement) g.HTMLElement = w.HTMLElement;
+  if (!g.HTMLVideoElement) g.HTMLVideoElement = w.HTMLVideoElement;
+  if (!g.HTMLAudioElement) g.HTMLAudioElement = w.HTMLAudioElement;
+  if (!g.HTMLCanvasElement) g.HTMLCanvasElement = w.HTMLCanvasElement;
+  if (!g.MediaStream) g.MediaStream = w.MediaStream || class MediaStream { getTracks() { return []; } };
+  if (!g.MediaStreamTrack) g.MediaStreamTrack = w.MediaStreamTrack || class MediaStreamTrack {};
+  if (!g.Blob) g.Blob = w.Blob;
+  if (!g.FileReader) g.FileReader = w.FileReader;
+  if (!g.CustomEvent) g.CustomEvent = w.CustomEvent;
+  if (!g.Event) g.Event = w.Event;
+  if (!g.EventTarget) g.EventTarget = w.EventTarget;
+  if (!g.XMLHttpRequest) g.XMLHttpRequest = w.XMLHttpRequest;
+  if (!g.FormData) g.FormData = w.FormData;
+  if (!g.URL) g.URL = w.URL;
+  if (!g.URLSearchParams) g.URLSearchParams = w.URLSearchParams;
+  if (!g.requestAnimationFrame) g.requestAnimationFrame = w.requestAnimationFrame.bind(w);
+  if (!g.cancelAnimationFrame) g.cancelAnimationFrame = w.cancelAnimationFrame.bind(w);
+
+  // Round 6 fix: FormData realm mismatch breaking jsdom XHR multipart bodies.
+  //
+  // Node.js >= 18 ships a global FormData (from undici). The UMD bundle runs
+  // in the Node global scope, so `new FormData()` inside the SDK constructs an
+  // UNDICI FormData — the `if (!g.FormData) g.FormData = w.FormData` line above
+  // never fires because the global already exists. jsdom's XMLHttpRequest only
+  // recognises ITS OWN realm's FormData (via jsdom's internal FormData impl
+  // check); an undici FormData falls through the default branch of jsdom's
+  // send() and is coerced with ToString() to the literal string
+  // "[object FormData]" (17 bytes). Every multipart/form-data request the SDK
+  // makes (AP access point POST /api/v2/transpond/webrtc, webproxy join) then
+  // carries that garbage body: Agora's nginx returns 502 (no CORS headers on
+  // the error response), jsdom's CORS validator rejects it, and the SDK sees
+  // NETWORK_ERROR before the access-point layer is ever exercised.
+  //
+  // Fix: wrap jsdom XMLHttpRequest.prototype.send so a foreign (non-jsdom)
+  // FormData-like body is converted into a real jsdom FormData with the same
+  // entries. The resulting multipart/form-data body is genuinely serialized
+  // and sent — this is a realm-bridge polyfill, not a mock: the server
+  // receives the real field values the SDK appended.
+  try {
+    const jsdomXHR = w.XMLHttpRequest;
+    const jsdomFormData = w.FormData;
+    const origXhrSend = jsdomXHR.prototype.send;
+    jsdomXHR.prototype.send = function (body) {
+      let out = body;
+      if (
+        body &&
+        typeof body === "object" &&
+        typeof body.entries === "function" &&
+        typeof body.append === "function" &&
+        !(body instanceof jsdomFormData)
+      ) {
+        const fd = new jsdomFormData();
+        for (const [name, value] of body.entries()) {
+          // Entries are strings (the SDK only appends string fields).
+          // Foreign Blob/File values are forwarded as-is; jsdom accepts any
+          // Blob for append.
+          fd.append(name, value);
+        }
+        out = fd;
+      }
+      return origXhrSend.call(this, out);
+    };
+  } catch (e) {
+    // If the jsdom prototype is not writable in this jsdom version, leave it
+    // untouched — behavior degrades to the pre-Round-6 state, nothing masked.
+  }
+
+  // WebCrypto capability exposure (Round 4).
+  //
+  // Node.js >= 19 ships a genuine WebCrypto implementation as a global
+  // (globalThis.crypto.subtle). jsdom's window.crypto does NOT implement
+  // SubtleCrypto, so the SDK's capability probe
+  //   supportWebCrypto = typeof window !== "undefined"
+  //                      && window.crypto !== undefined
+  //                      && window.crypto.subtle !== undefined
+  // reported false even though a real WebCrypto backend exists in the host
+  // runtime. Exposing the host's real implementation on the jsdom window
+  // makes the detection reflect actual capability (this is NOT a polyfill or
+  // stub — it is the runtime's own WebCrypto).
+  try {
+    const hostCrypto = globalThis.crypto;
+    if (
+      hostCrypto &&
+      typeof hostCrypto.subtle !== "undefined" &&
+      (typeof w.crypto === "undefined" || typeof w.crypto.subtle === "undefined")
+    ) {
+      Object.defineProperty(w, "crypto", { value: hostCrypto, configurable: true });
+    }
+  } catch (e) {
+    // If the jsdom window rejects the property redefinition, keep jsdom's
+    // crypto object — detection stays honest (false), functionality unaffected.
+  }
+
+  if (!g.getComputedStyle) g.getComputedStyle = w.getComputedStyle.bind(w);
+  if (!g.matchMedia) {
+    g.matchMedia = w.matchMedia
+      ? w.matchMedia.bind(w)
+      : () => ({ matches: false, addListener: noop, removeListener: noop, addEventListener: noop, removeEventListener: noop });
+  }
+  return true;
+}
+
+function createInMemoryStorage() {
+  const store = new Map();
+  return {
+    get length() { return store.size; },
+    key(i) { return Array.from(store.keys())[i] ?? null; },
+    getItem(k) { return store.has(String(k)) ? store.get(String(k)) : null; },
+    setItem(k, v) { store.set(String(k), String(v)); },
+    removeItem(k) { store.delete(String(k)); },
+    clear() { store.clear(); },
+  };
+}
+
+/**
+ * Storage shims. In-memory Storage is a real (if non-persistent)
+ * implementation of the Web Storage API semantics.
+ */
+function applyStorageShim() {
+  if (typeof globalThis.localStorage === "undefined") {
+    Object.defineProperty(globalThis, "localStorage", {
+      value: createInMemoryStorage(), configurable: true, writable: false,
+    });
+  }
+  if (typeof globalThis.sessionStorage === "undefined") {
+    Object.defineProperty(globalThis, "sessionStorage", {
+      value: createInMemoryStorage(), configurable: true, writable: false,
+    });
+  }
+}
+
+/**
+ * navigator.mediaDevices shim — honest for a Node.js runtime where no media
+ * capture devices are accessible:
+ *  - enumerateDevices() → resolves with an EMPTY list (factually correct:
+ *    no devices are exposed to a Node.js process).
+ *  - getUserMedia() → rejects (no capture devices available).
+ * This prevents the SDK's async device detection from producing unhandled
+ * rejections, without faking any device or capture capability.
+ */
+function applyMediaDevicesShim() {
+  const nav = globalThis.navigator;
+  if (!nav || nav.mediaDevices) return;
+  const notSupportedError = () => {
+    const err = new Error("getUserMedia is not supported in Node.js: no media capture devices available");
+    err.name = "NotSupportedError";
+    return err;
+  };
+  const mediaDevices = {
+    ondevicechange: null,
+    enumerateDevices: () => Promise.resolve([]),
+    getSupportedConstraints: () => ({}),
+    getUserMedia: () => Promise.reject(notSupportedError()),
+    getDisplayMedia: () => Promise.reject(notSupportedError()),
+    addEventListener: noop,
+    removeEventListener: noop,
+    dispatchEvent: () => true,
+  };
+  Object.defineProperty(nav, "mediaDevices", {
+    value: mediaDevices, configurable: true, writable: false,
+  });
+}
+
+/**
+ * WebRTC runtime injection (Round 2).
+ *
+ * HarmonyOS Node.js does not ship a W3C WebRTC implementation. The
+ * @ohos-ports/node-datachannel package provides a native OHOS arm64
+ * libdatachannel stack (RTCPeerConnection / RTCDataChannel / ICE / DTLS /
+ * SCTP) exposed through a genuine W3C-shaped polyfill (verified with a real
+ * in-process loopback: SDP exchange, ICE, DTLS handshake, DataChannel open).
+ *
+ * When this package is installed, its real W3C-surface classes are promoted
+ * to globals so the SDK's RTC transport (client.join / publish signaling)
+ * can run:
+ *   RTCPeerConnection, RTCSessionDescription, RTCIceCandidate,
+ *   RTCDataChannel, RTCPeerConnectionIceEvent, RTCDataChannelEvent, RTCError.
+ *
+ * W3C WebSocket: Node.js >= 22 ships a real, spec-compliant WebSocket client
+ * as a global — used as-is (no shim, no override).
+ *
+ * Media capture (navigator.mediaDevices.getUserMedia) stays honest: see
+ * applyMediaDevicesShim — libdatachannel has no camera/microphone capture,
+ * so local track creation reports NotSupportedError. join() without locally
+ * pre-created tracks works over the native stack.
+ */
+function applyWebRtcRuntimeShim() {
+  // Real WebRTC already present (browser or a runtime that provides it).
+  if (typeof globalThis.RTCPeerConnection !== "undefined") return true;
+
+  let polyfill = null;
+  try {
+    polyfill = require("@ohos-ports/node-datachannel/polyfill");
+  } catch (e) {
+    // Native WebRTC runtime not installed — RTC globals stay absent (honest).
+    return false;
+  }
+  if (!polyfill || typeof polyfill.RTCPeerConnection !== "function") return false;
+
+  const rtcGlobals = [
+    "RTCPeerConnection",
+    "RTCSessionDescription",
+    "RTCIceCandidate",
+    "RTCDataChannel",
+    "RTCPeerConnectionIceEvent",
+    "RTCDataChannelEvent",
+    "RTCError",
+  ];
+  for (const name of rtcGlobals) {
+    if (typeof globalThis[name] === "undefined" && typeof polyfill[name] !== "undefined") {
+      globalThis[name] = polyfill[name];
+    }
+  }
+
+  // Round 4: also promote the same real classes onto the browser `window`
+  // object. The SDK probes capabilities through window.* (e.g.
+  // window.RTCPeerConnection, window.RTCRtpSender) in several feature
+  // detectors; without this, those probes report false even though the real
+  // native WebRTC runtime is present and reachable via bare globals.
+  const jsdomWindow = globalThis.window;
+  if (jsdomWindow && jsdomWindow !== globalThis) {
+    for (const name of rtcGlobals) {
+      try {
+        if (
+          typeof jsdomWindow[name] === "undefined" &&
+          typeof polyfill[name] !== "undefined"
+        ) {
+          Object.defineProperty(jsdomWindow, name, { value: polyfill[name], configurable: true, writable: true });
+        }
+      } catch (e) {
+        // Property not definable on this window implementation — leave absent
+        // so detection stays honest.
+      }
+    }
+  }
+  return true;
+}
+
+function applyBrowserShim() {
+  // 1. Already a browser-like environment → nothing to do.
+  if (typeof globalThis.window !== "undefined" && globalThis.window.document) {
+    return false;
+  }
+
+  // 2. Full DOM environment via jsdom (preferred).
+  let applied;
+  try {
+    applied = applyJSDomShim();
+  } catch (e) {
+    // jsdom not installed — fall through to minimal shim.
+    applied = applyMinimalShim();
+  }
+
+  // 3. Shared honest shims for storage and media device enumeration.
+  applyStorageShim();
+  applyMediaDevicesShim();
+
+  // 4. Native WebRTC runtime injection (Round 2).
+  applyWebRtcRuntimeShim();
+
+  return applied;
+}
+
+module.exports = { applyBrowserShim };