@zero-server/sdk 0.9.10 → 1.0.0

package/README.md

@@ -12,8 +12,8 @@
 
 <p align="center">
   <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/tonywied17/zero-server/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
-  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7781%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
-  <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-95.85%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
+  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7891%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
+  <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-94.97%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
   <a href="https://z-server.dev"><img src="https://img.shields.io/badge/docs-z--server.dev-00d8e0?style=flat-square&logo=readthedocs&logoColor=white" alt="docs"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-00d8e0?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="MIT"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=nodedotjs&logoColor=white" alt="node >=18"></a>
@@ -55,7 +55,7 @@ npm install @zero-server/core @zero-server/body @zero-server/middleware
 | `@zero-server/auth` | `jwt`, `session`, `oauth`, `authorize`, `twoFactor`, `webauthn`, `trustedDevice`, `enrollment` |
 | `@zero-server/orm` | `Database`, `Model`, `Query`, `TYPES`, migrations, seeders, replicas, search, geo, tenancy, audit |
 | `@zero-server/realtime` | `WebSocketConnection`, `WebSocketPool`, `SSEStream` |
-| `@zero-server/webrtc` | signaling hub, rooms/peers, STUN/TURN, SFU adapters (memory, mediasoup, LiveKit), join tokens, E2EE, `spawnBotPeer` |
+| `@zero-server/webrtc` | `createWebRTC`, `SignalingHub`, `Room`/`Peer`, SDP/ICE parsers, STUN client, `TurnServer` + `issueTurnCredentials`, SFU adapters (memory, mediasoup, LiveKit), `signJoinToken`/`verifyJoinToken`, E2EE, cluster + cascade coordinators, MCU adapters, `RecordingManager`/`IngressManager`, `spawnBotPeer` |
 | `@zero-server/grpc` | gRPC server, client, codec, status, metadata, framing, health, reflection, balancer |
 | `@zero-server/observe` | `MetricsRegistry`, `Tracer`, structured `Logger`, health checks |
 | `@zero-server/lifecycle` | `LifecycleManager`, `ClusterManager`, `clusterize` |
@@ -167,6 +167,46 @@ const users = await User.find({ name: 'Alice' })
 - **WebSocket** - `app.ws(path, handler)` with RFC 6455, `WebSocketPool` for rooms, broadcasting, and sub-protocols
 - **Server-Sent Events** - `res.sse()` with auto-IDs, named events, and keep-alive
 
+### WebRTC
+
+Full WebRTC stack - signaling, SDP/ICE parsing, STUN client, TURN credential issuer, SFU adapters, end-to-end encryption, multi-node clustering, and a headless bot peer:
+
+```js
+const { createApp, createWebRTC } = require('@zero-server/sdk')
+const app = createApp()
+
+const rtc = createWebRTC(app, {
+    path: '/rtc',
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+})
+
+rtc.on('peer:joined', ({ room, peer }) => {
+    console.log(`peer ${peer.id} joined ${room.id}`)
+})
+
+app.listen(3000)
+```
+
+| Feature | Description |
+|---|---|
+| Signaling | `SignalingHub` over WebSocket, `Room` / `Peer` model with join/leave/offer/answer/ICE relay |
+| SDP & ICE | `parseSdp` / `stringifySdp`, `parseCandidate` / `stringifyCandidate` / `filterCandidates`, private/loopback/link-local/mDNS detection |
+| STUN | RFC 5389 client - `stunBinding`, `encodeBindingRequest`, `decodeMessage`, XOR-MAPPED-ADDRESS helpers |
+| TURN | Built-in `TurnServer` (UDP allocations, channels, permissions) plus time-limited `issueTurnCredentials` (REST API spec) |
+| SFU adapters | `SfuAdapter` interface with `MemorySfuAdapter`, `MediasoupSfuAdapter`, `LiveKitSfuAdapter`, and `loadSfuAdapter()` for dynamic selection |
+| Join tokens | `signJoinToken` / `verifyJoinToken` for short-lived signed room admission |
+| End-to-end encryption | `E2eeChannel`, `attachE2ee`, `generateE2eeKeyPair`, `sealKey`, `openSealedKey` (sealed-sender key exchange) |
+| Clustering | `useCluster`, `ClusterCoordinator`, `MemoryClusterAdapter` for multi-node room state + region-aware bridge selection |
+| Cascade | `useCascade`, `CascadeCoordinator` to fan producers across SFU nodes via `pipeToRouter` (mediasoup-style) |
+| MCU | `McuAdapter`, `MemoryMcuAdapter`, `FfmpegMcuAdapter` for audio/video mixing on top of any SFU |
+| Recording & ingress | `RecordingManager` (LiveKit egress / ffmpeg / bookkeeping) and `IngressManager` (WHIP, RTMP, SIP, URL pull) |
+| Bot peer | `spawnBotPeer()` headless server-side peer for testing, recording, and automated agents |
+| Observability | `bindObservability(rtc, { metrics, logger })` for Prometheus metrics and structured logs |
+| Errors | `WebRTCError`, `SignalingError`, `IceError`, `TurnError`, `SdpError` |
+| CLI | `runWebRTCCommand` - `npx zs webrtc turn:cred`, `webrtc sdp:parse`, etc. |
+
+> **Scaling beyond a single node?** See [docs/scopes/webrtc-scaling.md](docs/scopes/webrtc-scaling.md) for the topology decision tree (mesh → SFU → cascade → MCU), capacity rules of thumb, and end-to-end multi-region examples.
+
 ### Observability
 
 Built-in Prometheus metrics, health checks, distributed tracing, and structured logging - zero dependencies.
@@ -371,6 +411,26 @@ const {
   // Real-time
   WebSocketConnection, WebSocketPool, SSEStream,
 
+  // WebRTC
+  createWebRTC, SignalingHub, Room, Peer,
+  parseSdp, stringifySdp,
+  parseCandidate, stringifyCandidate, filterCandidates,
+  isPrivateIp, isLoopbackIp, isLinkLocalIp, isMdnsHostname,
+  stunBinding, encodeBindingRequest, decodeMessage,
+  encodeXorMappedAddress, decodeXorMappedAddress,
+  STUN_MAGIC_COOKIE, STUN_METHOD, STUN_CLASS, STUN_ATTR,
+  issueTurnCredentials, TurnServer,
+  SfuAdapter, MemorySfuAdapter, MediasoupSfuAdapter, LiveKitSfuAdapter,
+  loadSfuAdapter, signJoinToken, verifyJoinToken,
+  spawnBotPeer, bindObservability,
+  E2eeChannel, attachE2ee, generateE2eeKeyPair, sealKey, openSealedKey,
+  useCluster, ClusterCoordinator, MemoryClusterAdapter,
+  useCascade, CascadeCoordinator, CH_CASCADE,
+  McuAdapter, MemoryMcuAdapter, FfmpegMcuAdapter,
+  RecordingManager, IngressManager,
+  runWebRTCCommand,
+  WebRTCError, SignalingError, IceError, TurnError, SdpError,
+
   // gRPC
   GrpcStatus, grpcToHttp, grpcStatusName, GRPC_STATUS_NAMES,
   GrpcMetadata, ProtoWriter, ProtoReader, protoEncode, protoDecode,
@@ -440,6 +500,8 @@ lib/
                          replicas, search, geo, tenancy, audit, views, procedures, plugins
   router/             - Router with sub-app mounting and pattern matching
   sse/                - SSE stream controller
+  webrtc/             - signaling hub, SDP/ICE, STUN client, TURN server, SFU adapters,
+                         join tokens, E2EE, clustering, bot peer, CLI
   ws/                 - WebSocket connection, handshake, and room management
 packages/             - generated scoped @zero-server/* re-exports (one dir per scope)
 .tools/

package/index.js

@@ -73,6 +73,9 @@ const {
     bindObservability,
     E2eeChannel, attachE2ee, generateE2eeKeyPair, sealKey, openSealedKey,
     useCluster, ClusterCoordinator, MemoryClusterAdapter,
+    useCascade, CascadeCoordinator, CH_CASCADE,
+    McuAdapter, MemoryMcuAdapter, FfmpegMcuAdapter,
+    RecordingManager, IngressManager,
     runWebRTCCommand,
     WebRTCError, SignalingError, IceError, TurnError, SdpError,
 } = require('./lib/webrtc');
@@ -509,6 +512,22 @@ module.exports = {
     ClusterCoordinator,
     /** @see module:webrtc/cluster */
     MemoryClusterAdapter,
+    /** @see module:webrtc/cascade */
+    useCascade,
+    /** @see module:webrtc/cascade */
+    CascadeCoordinator,
+    /** @see module:webrtc/cascade */
+    CH_CASCADE,
+    /** @see module:webrtc/mcu */
+    McuAdapter,
+    /** @see module:webrtc/mcu */
+    MemoryMcuAdapter,
+    /** @see module:webrtc/mcu/ffmpeg */
+    FfmpegMcuAdapter,
+    /** @see module:webrtc/recording */
+    RecordingManager,
+    /** @see module:webrtc/recording */
+    IngressManager,
     /** @see module:webrtc/cli */
     runWebRTCCommand,
     /** @see module:errors */