@streaming-cdn/rtc-web 1.3.10

package/README.md

@@ -0,0 +1,175 @@
+# RTC Web SDK 1.3.9
+
+The customer package contains compiled ESM/UMD JavaScript and TypeScript declarations. It intentionally excludes implementation source and source maps. Example source remains available under `examples/`.
+
+Install the package from the extracted archive or publish it to your private npm registry. Verify the archive against `SHA256SUMS.txt`; a Server API key must never be placed in browser code.
+
+## Integration modes
+
+| Mode | Use | Required APIs |
+| --- | --- | --- |
+| Media only | Your app already owns dialing, push, and UI | `createRtcClient()` |
+| Managed signaling, custom UI | Online presence and call events, rendered by your app | `createRtcIncomingClient()` without `mount` |
+| Custom signaling or push, SDK call UI | Your delivery channel injects calls into the SDK | `autoConnect: false`, `handleIncomingCall()` |
+| Managed signaling and SDK call UI | Fastest complete integration | `signalingUrl` plus `mount` |
+
+## Media only
+
+Your backend creates or accepts the call and returns only the participant credential.
+
+```ts
+import { createRtcClient } from "@streaming-cdn/rtc-web";
+
+const media = await createRtcClient({
+  mode: "video",
+  credential: response.credential,
+  autoJoin: true,
+  quality: "auto",
+  preferredVideoCodec: "h264"
+});
+
+// Bind tracks from the native client to any DOM/framework renderer.
+const nativeClient = media.getNativeClient();
+```
+
+No iframe, push adapter, incoming UI, or signaling client is created.
+
+For a receive-only device, disable local capture without disabling remote
+media negotiation:
+
+```ts
+const media = await createRtcClient({
+  mode: "video", credential: response.credential,
+  audio: false, video: false,
+  receiveAudio: true, receiveVideo: true
+});
+media.addEventListener("remotestream", ({ detail }) => {
+  const { participant, stream, track } = detail.detail;
+  attachRemoteStream(participant, stream, track);
+});
+await media.join();
+```
+
+`localstream` carries `{ stream }`; `remotestream` carries
+`{ participant, stream, track }`. Register both listeners before `join()`.
+
+## Managed signaling with custom UI
+
+```ts
+const phone = createRtcIncomingClient({
+  tokenProvider: async () => {
+    const response = await fetch("/api/rtc/client-token", { credentials: "include" });
+    if (!response.ok) throw new Error("Unable to refresh RTC identity");
+    return response.json(); // { token, expiresAt }
+  },
+  signalingUrl,
+  onEvent(event) {
+    if (event.type === "presence") renderOnlineUsers(event.detail.users);
+    if (event.type === "incomingcall") showYourIncomingUi(event.detail);
+    if (event.type === "callupdated") updateYourCallUi(event.detail);
+  }
+});
+
+const accepted = await phone.accept(callId);
+const media = await createRtcClient({ mode: "video", credential: accepted.credential!, autoJoin: true });
+phone.attachMediaClient(callId, media);
+```
+
+## Custom push or signaling with SDK UI
+
+```ts
+const phone = createRtcIncomingClient({
+  tokenProvider: async () => {
+    const response = await fetch("/api/rtc/client-token", { credentials: "include" });
+    if (!response.ok) throw new Error("Unable to refresh RTC identity");
+    return response.json();
+  },
+  apiBaseUrl: "https://streaming-cdn.ewin888.com",
+  autoConnect: false,
+  mount: document.querySelector("#incoming-call")
+});
+
+yourPush.onMessage((payload) => phone.handleIncomingCall({
+  id: payload.callId,
+  mode: payload.mode,
+  status: "ringing",
+  caller: { id: payload.callerId, name: payload.callerName }
+}));
+```
+
+Omit `mount` when your application also owns the incoming-call UI. Call `accept`, `reject`, `busy`, `end`, or `cancel` from your own controls.
+
+For outgoing UI, show `contacting` while mobile push is being delivered, move to `ringing` on `call.delivery`, and show `connected` only after both `call.updated: accepted` and the media client's `connected` event. Do not call `join()` before acceptance. Cancel unanswered calls at the invitation `expiresAt` timestamp (45 seconds by default).
+
+## Complete managed integration
+
+```ts
+const phone = createRtcIncomingClient({
+  tokenProvider: async () => {
+    const response = await fetch("/api/rtc/client-token", { credentials: "include" });
+    if (!response.ok) throw new Error("Unable to refresh RTC identity");
+    return response.json();
+  },
+  signalingUrl,
+  mount: "#incoming-call",
+  // Built-in incoming and outgoing tones are enabled by default.
+  // These URLs are optional and replace the built-in tones.
+  ringtoneUrl: "/audio/incoming.mp3",
+  ringbackUrl: "/audio/ringback.mp3",
+  terminalStateDurationMs: 1600
+});
+
+// Call this synchronously from the first click/tap in your UI so later
+// signaling events can play audio under browser autoplay policies.
+await unlockRtcCallAudio();
+const outgoing = await phone.startCall({ mode: "voice", target: { id: "user-42", name: "Alex" } });
+const media = await createRtcClient({ mode: "voice", credential: outgoing.credential!, autoJoin: true });
+phone.attachMediaClient(String(outgoing.call.id), media);
+```
+
+Set `sounds: false` to disable SDK call audio. If `ringtoneUrl` or `ringbackUrl` is omitted, the SDK synthesizes a default tone and does not require an audio asset. The built-in incoming-call UI keeps terminal states such as declined, busy, missed, failed, and ended visible for 1.6 seconds before closing; change this with `terminalStateDurationMs`.
+
+## Lifecycle
+
+1. Your backend holds the long-lived Server API key and exposes an authenticated application endpoint such as `/api/rtc/client-token`.
+2. `tokenProvider` calls that endpoint. The SDK refreshes the short-lived identity before expiry, before reconnect, and once after an HTTP `401`.
+3. The client optionally opens `/v1/rtc/signaling` for presence and call events.
+4. The caller starts a call. Only the caller receives a media credential at this point.
+5. The callee accepts. The first accepting device wins atomically and receives its credential.
+6. Both clients initialize `createRtcClient()`, join media, and render tracks.
+7. Either side ends the call and destroys media/signaling clients during teardown.
+
+The Server API key is long-lived until revoked and must remain on the application backend. Do not place it in JavaScript, an APK, an IPA, desktop binaries, or application configuration. The `rtcc_...` identity is deliberately short-lived and is not a deployment secret that staff should replace manually.
+
+`attachMediaClient(callId, media)` is the recommended lifecycle API. It stops
+statistics, leaves media, and releases camera/microphone tracks when either
+side receives a terminal call state. Manual integrations must call
+`await media.leave(); media.destroy()` for `ended`, `cancelled`, `rejected`,
+`busy`, `failed`, and `missed`. Calling the same terminal action twice is safe.
+
+## Quality and codecs
+
+Use `setQuality("low" | "medium" | "high" | "audio" | "auto")` at runtime.
+`auto` is the default for video and uses interval packet loss, RTT, and the
+available outgoing bitrate plus encoder CPU/bandwidth limits to step down
+quickly and recover conservatively. It starts at `medium`; severe latency or
+loss falls directly to `low`, while promotion requires six healthy samples.
+Use `setPreferredVideoCodec("vp8" | "h264" | "auto")`; compatible fallback
+codecs remain in the offer. `packetLossPct` is the loss measured since the
+previous sample. `packetLossCumulativePct` is the value since the call began.
+
+Use `iceTransportPolicy: "relay"` to compare a poor direct carrier route with a
+relay-only route. The default `all` policy allows both direct and relay
+candidates. Relay-only mode requires valid relay credentials and should be
+chosen from measured RTT/loss data rather than enabled blindly.
+
+See `docs/RTC_SDK_INTEGRATION.md` in the source repository for sequence diagrams and server examples.
+
+Managed signaling uses a 20-second heartbeat and reconnects with jittered
+exponential backoff. WebSocket close code `1006` is recoverable but not a
+normal healthy close. A still-ringing invitation created during an outage is
+replayed after reconnection until its 45-second expiry; terminal calls are not.
+Abnormal close, reconnect, and recovery duration are also sent as bounded
+operational diagnostics. Tokens, SDP, media, and chat content are never part of
+that report. Set `reportSignalingDiagnostics: false` only when replacing this
+with an application-owned diagnostics pipeline.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@streaming-cdn/rtc-web",
+  "version": "1.3.10",
+  "type": "module",
+  "main": "dist/rtc-web.umd.js",
+  "module": "dist/rtc-web.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/rtc-web.es.js",
+      "require": "./dist/rtc-web.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt",
+    "NOTICE.md"
+  ],
+  "license": "SEE LICENSE IN LICENSE.txt"
+}