openrtc 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# OpenRTC TypeScript Package
+
+The TypeScript package is the host-facing layer for `openrtc`.
+
+It does not implement a second realtime engine. It exposes the Rust runtime to:
+- browser apps through WASM plus the scoped browser Firebase signaling layer
+- native apps through a generic IPC contract, with first-party Tauri wiring in `openrtc-tauri`
+
+## Recommended Usage
+
+Use the OpenRTC client entry points for new integrations:
+
+```ts
+import { OpenRTC } from 'openrtc';
+
+const client = OpenRTC({
+  apiKey: 'pk_live_...',
+  authMode: 'external',
+});
+
+await client.connect();
+```
+
+For normal app code, the default flow is:
+
+1. discover or select a `deviceId`
+2. call `connectPeer(...)` or `connectToDevice(...)`
+3. wait for `waitForConnectedPeer(deviceId)`
+4. open peer-targeted streams with `openPeerBi(...)` / `openPeerUni(...)`
+
+Low-level peer handles returned by runtime methods, along with `openPeerBi(deviceId)` and `openPeerUni(deviceId)`, remain available for advanced runtime flows, but they are not the default integration model.
+
+## What This Package Owns
+- runtime factories and adapters
+- auth context injection
+- Pluto hosted auth helpers
+- browser Firebase signaling/rooms wiring
+- host wiring for WASM and generic IPC
+
+## What This Package Does Not Own
+- native Tauri API bindings
+- peer discovery or lifecycle policy beyond the browser Firebase host layer
+- iroh connection lifecycle
+
+Those responsibilities belong to the Rust runtime and the host platform adapter.
+
+## Message Model
+- `openrtc` is message-agnostic above the runtime layer.
+- The runtime only defines internal control messages such as handshake and heartbeat.
+- Application payload protocols, including file transfer, should be implemented on top of generic runtime connections and streams.
+- If an app needs richer payload ergonomics, add generic stream/connection primitives to the runtime instead of adding app-specific message types to `pluto-rtc`.
+
+## Protocol Extension Model
+
+The recommended TypeScript extension path is:
+
+1. wait for a Rust-backed connected peer session
+2. open a bidirectional or unidirectional stream
+3. implement your own framing and message semantics in app code
+
+This keeps the runtime responsible for peer/session establishment while leaving
+full control of channel/message specifics to the developer.
+
+Advanced custom ALPN protocol plugins are a Rust-first/native-first feature.
+Browser parity is guaranteed at the connected-peer stream layer, not at the
+full ALPN plugin layer.
+
+## Main Surfaces
+
+### Root Package
+- `OpenRTC()`
+- `OpenRTC.native()`
+- `Client` (re-export alias)
+- `RuntimeClient`
+
+### Runtime Secondary Entrypoint
+- `openrtc/runtime`
+- `createWasmClient()` and `createIpcClient(..., bridge)` (legacy compatibility)
+- `IpcRuntimeAdapter`
+- `WasmRuntimeAdapter`
+- `PlutoIpcBridge` types for advanced host integrations
+
+### Tauri Package
+- `openrtc-tauri`
+- `createTauriIpcBridge()`
+- `TauriRuntimeAdapter`
+- `openrtc/runtime/tauri` remains as a deprecated compatibility shim for one release cycle
+
+## Auth Model
+- `anonymous`: no Pluto auth required
+- `required`: Pluto auth required; the SDK may initiate Pluto SSO
+- `external`: Pluto auth still required, but the host app acquires it and injects it into the runtime
+
+## Design Rule
+If a feature requires discovery, signaling, presence, or lifecycle state, the TypeScript package should delegate to Rust rather than reimplement it locally, except for the scoped browser Firebase host layer where the official browser SDK is the source of truth.
+
+## Allowed vs. Not Allowed
+
+- Allowed:
+  - host/runtime adapter selection
+  - auth injection and hosted Pluto auth helpers
+  - thin, typed wrappers over Rust-owned state
+- Not allowed:
+  - TypeScript-owned discovery or lifecycle engines
+  - TypeScript-owned peer identity policy
+  - app-specific protocol messages embedded into the runtime

package/dist/OpenRTC.d.ts

@@ -0,0 +1,71 @@
+/**
+ * OpenRTC — simplified developer-facing entry point.
+ *
+ * Usage:
+ *   import { OpenRTC } from 'openrtc';
+ *   const client = OpenRTC({ apiKey: 'pk_live_...' });
+ *   await client.connect();
+ *
+ * For native (Tauri) apps:
+ *   const client = OpenRTC.native({ apiKey: 'pk_live_...' });
+ *
+ * The returned Client object combines RuntimeClient methods with
+ * auth helpers (setAuth, syncPlutoAuth, bindPlutoAuthHost, signIn, signOut).
+ *
+ * Backward compatibility:
+ *   - createWasmClient() and createIpcClient() remain available from `openrtc/runtime`
+ *   - PlutoRuntimeAssembly remains available from `openrtc/runtime`
+ *   - RuntimeClient is still re-exported as Client
+ */
+import type { AuthContext } from './core/IEngineBridge';
+import type { ClientOptions } from './core/types';
+import { RuntimeClient } from './runtime/RuntimeClient';
+import { type PlutoRuntimeAssembly } from './runtime/factories';
+import { type PlutoIpcBridge } from './runtime/ipc';
+/**
+ * OpenRTCClient extends RuntimeClient with auth helpers that were
+ * previously only available on PlutoRuntimeAssembly.
+ *
+ * This is the unified type returned by OpenRTC() and OpenRTC.native().
+ */
+export interface OpenRTCClient extends RuntimeClient {
+    /** @deprecated Use setAuth() instead */
+    setAuthContext(context: AuthContext | null): Promise<void>;
+    /** Set auth context for the runtime */
+    setAuth(context: AuthContext | null): Promise<void>;
+    /** Sync Pluto-hosted auth to the runtime */
+    syncPlutoAuth(options?: {
+        userId?: string | null;
+        forceRefresh?: boolean;
+    }): Promise<void>;
+    /** Bind Pluto auth host to auto-sync on token changes */
+    bindPlutoAuthHost(): () => void;
+    /** Sign in via Pluto SSO */
+    signIn(): Promise<void>;
+    /** Sign out and clear auth context */
+    signOut(): Promise<void>;
+    /**
+     * Access to the underlying PlutoRuntimeAssembly for backward compatibility.
+     * @deprecated Access methods directly on the client instead.
+     */
+    readonly runtime: RuntimeClient;
+    /**
+     * Access to the underlying PlutoRuntimeAssembly for backward compatibility.
+     * @internal
+     */
+    readonly _assembly: PlutoRuntimeAssembly;
+}
+/**
+ * Create an OpenRTC client for browser/WASM environments.
+ *
+ * @example
+ * ```typescript
+ * import { OpenRTC } from 'openrtc';
+ * const client = OpenRTC({ apiKey: 'pk_live_...' });
+ * await client.connect();
+ * ```
+ */
+export declare function OpenRTC(options: ClientOptions): OpenRTCClient;
+export declare namespace OpenRTC {
+    var native: (options: ClientOptions, bridge?: PlutoIpcBridge) => OpenRTCClient;
+}

package/dist/OpenRTC.js

@@ -0,0 +1,130 @@
+/**
+ * OpenRTC — simplified developer-facing entry point.
+ *
+ * Usage:
+ *   import { OpenRTC } from 'openrtc';
+ *   const client = OpenRTC({ apiKey: 'pk_live_...' });
+ *   await client.connect();
+ *
+ * For native (Tauri) apps:
+ *   const client = OpenRTC.native({ apiKey: 'pk_live_...' });
+ *
+ * The returned Client object combines RuntimeClient methods with
+ * auth helpers (setAuth, syncPlutoAuth, bindPlutoAuthHost, signIn, signOut).
+ *
+ * Backward compatibility:
+ *   - createWasmClient() and createIpcClient() remain available from `openrtc/runtime`
+ *   - PlutoRuntimeAssembly remains available from `openrtc/runtime`
+ *   - RuntimeClient is still re-exported as Client
+ */
+import { createWasmClient, createIpcClient } from './runtime/factories';
+import { createCompatTauriIpcBridge } from './runtime/ipc';
+function resolveOptions(options) {
+    // Map new option names to old ones (new names take priority)
+    const resolved = { ...options };
+    // auth → authMode
+    if ('auth' in options && !options.authMode) {
+        const auth = options.auth;
+        resolved.authMode = auth === 'none' ? 'anonymous' : auth;
+    }
+    // identity → nodeIdPersistence
+    if ('identity' in options && !options.nodeIdPersistence) {
+        const identity = options.identity;
+        resolved.nodeIdPersistence = identity === 'temporary' ? 'ephemeral' : identity;
+    }
+    // namespace → storagePrefix
+    if ('namespace' in options && !options.storagePrefix) {
+        resolved.storagePrefix = options.namespace;
+    }
+    // privacy → strictMode
+    if ('privacy' in options && options.strictMode === undefined) {
+        resolved.strictMode = !!options.privacy;
+    }
+    return resolved;
+}
+function wrapAssembly(assembly) {
+    const runtime = assembly.runtime;
+    // Create a proxy that delegates to RuntimeClient but adds assembly helpers
+    const client = Object.create(runtime);
+    // Assembly auth helpers as direct methods
+    Object.defineProperties(client, {
+        setAuth: {
+            value: (context) => assembly.setAuthContext(context),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        setAuthContext: {
+            value: (context) => assembly.setAuthContext(context),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        syncPlutoAuth: {
+            value: (options) => assembly.syncPlutoAuth(options),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        bindPlutoAuthHost: {
+            value: () => assembly.bindPlutoAuthHost(),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        signIn: {
+            value: () => assembly.signInWithPluto(),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        signOut: {
+            value: () => assembly.signOut(),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        },
+        // Backward compat: .runtime returns the RuntimeClient
+        runtime: {
+            get: () => runtime,
+            enumerable: false,
+        },
+        _assembly: {
+            get: () => assembly,
+            enumerable: false,
+        },
+    });
+    return client;
+}
+/**
+ * Create an OpenRTC client for browser/WASM environments.
+ *
+ * @example
+ * ```typescript
+ * import { OpenRTC } from 'openrtc';
+ * const client = OpenRTC({ apiKey: 'pk_live_...' });
+ * await client.connect();
+ * ```
+ */
+export function OpenRTC(options) {
+    const resolved = resolveOptions(options);
+    const assembly = createWasmClient(resolved);
+    return wrapAssembly(assembly);
+}
+/**
+ * Create an OpenRTC client for native (Tauri/IPC) environments.
+ * Auto-detects the Tauri IPC bridge.
+ *
+ * @example
+ * ```typescript
+ * import { OpenRTC } from 'openrtc';
+ * const client = OpenRTC.native({ apiKey: 'pk_live_...' });
+ * await client.connect();
+ * ```
+ */
+OpenRTC.native = function (options, bridge) {
+    const resolved = resolveOptions(options);
+    const ipcBridge = bridge ?? createCompatTauriIpcBridge();
+    const assembly = createIpcClient(resolved, ipcBridge);
+    return wrapAssembly(assembly);
+};

package/dist/api/MediaTransport.d.ts

@@ -0,0 +1,7 @@
+export declare class MediaTransport {
+    static sendTrack(track: MediaStreamTrack, sendFn: (data: Uint8Array) => Promise<void>): Promise<{
+        stop: () => void;
+        requestKeyFrame: () => void;
+    } | void>;
+    static receiveTrack(kind: 'audio' | 'video', onKeyFrameRequest?: () => void): MediaStreamTrack | null;
+}

package/dist/api/MediaTransport.js

@@ -0,0 +1,262 @@
+// Protocol-ish logic for transforming MediaStreamTracks into Chunks and back.
+// Since we don't have VideoEncoder/VideoDecoder in standard ts environment (it's web only),
+// we will just define the interfaces or classes here.
+// We use type 'any' for WebCodecs interfaces to avoid TS errors in environemnts without @types/dom-webcodecs
+export class MediaTransport {
+    // Encodes a track into the connection
+    static async sendTrack(track, sendFn) {
+        console.log(`[MediaTransport] sendTrack called for ${track.kind}`);
+        if ((typeof VideoEncoder === 'undefined') && (typeof AudioEncoder === 'undefined')) {
+            console.error("WebCodecs API not supported.");
+            return;
+        }
+        const processor = new window.MediaStreamTrackProcessor({ track });
+        const reader = processor.readable.getReader();
+        // Very basic encoder setup. 
+        // In reality we need to negotiate codecs. We assume VP8 for video and Opus for audio.
+        let encoder = null;
+        if (track.kind === 'video') {
+            let seqNum = 0;
+            encoder = new window.VideoEncoder({
+                output: (chunk, metadata) => {
+                    if (chunk.type === 'key') {
+                        console.log(`[MediaTransport] Generated KEY frame for video. Size: ${chunk.byteLength}`);
+                    }
+                    // console.log(`[MediaTransport] Encoded video chunk. Key: ${chunk.type}, Size: ${chunk.byteLength}`);
+                    // Send chunk
+                    // We need to serialize the chunk. 
+                    // [MAGIC 1b][timestamp 8 bytes][isKey 1 byte][seq 2 bytes][data...]
+                    const buffer = new ArrayBuffer(12 + chunk.byteLength);
+                    const view = new DataView(buffer);
+                    view.setUint8(0, 0x77); // Magic byte
+                    view.setBigInt64(1, BigInt(chunk.timestamp), false); // Big Endian
+                    view.setUint8(9, chunk.type === 'key' ? 1 : 0);
+                    const seq = (seqNum++) % 65536;
+                    view.setUint16(10, seq, false);
+                    const data = new Uint8Array(buffer);
+                    chunk.copyTo(new Uint8Array(buffer, 12));
+                    sendFn(data).catch(e => {
+                        const msg = (e.message || String(e)).toLowerCase();
+                        if (msg.includes("connection is closed") || msg.includes("connection closed") || msg.includes("sending stopped by peer")) {
+                            console.log(`[MediaTransport] Connection closed/stopped, stopping video encoder.`);
+                            if (encoder) {
+                                encoder.close();
+                                encoder = null;
+                            }
+                        }
+                        else {
+                            console.error("Send media failed", e);
+                        }
+                    });
+                },
+                error: (e) => console.error("VideoEncoder error", e)
+            });
+            encoder.configure({
+                codec: 'vp8',
+                width: 640,
+                height: 480,
+                bitrate: 500000, // 500 Kbps - Reduce congestion
+                framerate: 24, // slightly lower framerate
+                latencyMode: 'realtime', // Critical for low latency streaming
+            });
+        }
+        else if (track.kind === 'audio') {
+            encoder = new window.AudioEncoder({
+                output: (chunk, metadata) => {
+                    const buffer = new ArrayBuffer(9 + chunk.byteLength);
+                    const view = new DataView(buffer);
+                    view.setUint8(0, 0x77); // Magic
+                    view.setBigInt64(1, BigInt(chunk.timestamp), false);
+                    const data = new Uint8Array(buffer);
+                    chunk.copyTo(new Uint8Array(buffer, 9));
+                    sendFn(data).catch(e => {
+                        const msg = (e.message || String(e)).toLowerCase();
+                        if (msg.includes("connection is closed") || msg.includes("connection closed")) {
+                            console.log(`[MediaTransport] Connection closed, stopping audio encoder.`);
+                            if (encoder) {
+                                encoder.close();
+                                encoder = null;
+                            }
+                        }
+                        else {
+                            console.error("Send audio failed", e);
+                        }
+                    });
+                },
+                error: (e) => console.error("AudioEncoder error", e)
+            });
+            encoder.configure({
+                codec: 'opus',
+                sampleRate: 48000,
+                numberOfChannels: 1
+            });
+        }
+        // Read loop - Run asynchronously so we can return the controller immediately
+        (async () => {
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        console.log(`[MediaTransport] Reader done for ${track.kind}`);
+                        break;
+                    }
+                    if (value) {
+                        try {
+                            if (encoder && encoder.state !== 'closed') {
+                                const forceKey = encoder.forceKeyFrame;
+                                if (forceKey) {
+                                    console.log(`[MediaTransport] Forcing Key Frame now.`);
+                                    encoder.encode(value, { keyFrame: true });
+                                    encoder.forceKeyFrame = false;
+                                }
+                                else {
+                                    encoder.encode(value);
+                                }
+                            }
+                        }
+                        finally {
+                            value.close();
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                console.error(`[MediaTransport] Read loop error for ${track.kind}:`, e);
+            }
+        })();
+        // Return controller
+        return {
+            stop: () => {
+                // TODO: Close processor and reader
+            },
+            requestKeyFrame: () => {
+                if (encoder && encoder.state === 'configured') {
+                    console.log(`[MediaTransport] Key Frame Requested for ${track.kind}`);
+                    // We can't force it here directly because we are in a read loop.
+                    // But we can set a flag that the loop checks.
+                    encoder.forceKeyFrame = true;
+                }
+                else {
+                    console.warn(`[MediaTransport] Impossible to request KeyFrame: Encoder state is ${encoder?.state}`);
+                }
+            }
+        };
+    }
+    // Receives chunks and outputs a MediaStreamTrack
+    static receiveTrack(kind, onKeyFrameRequest) {
+        if ((typeof VideoDecoder === 'undefined') && (typeof AudioDecoder === 'undefined')) {
+            console.warn("WebCodecs API not supported.");
+            return null;
+        }
+        const generator = new window.MediaStreamTrackGenerator({ kind });
+        const writer = generator.writable.getWriter();
+        let decoder = null;
+        // Throttling for PLI
+        let lastPli = 0;
+        let expectedSeq = null;
+        if (kind === 'video') {
+            decoder = new window.VideoDecoder({
+                output: (frame) => {
+                    try {
+                        writer.write(frame);
+                    }
+                    finally {
+                        frame.close();
+                    }
+                },
+                error: (e) => console.error("VideoDecoder error", e)
+            });
+            decoder.configure({
+                codec: 'vp8'
+            });
+            // Force wait for key frame immediately
+            decoder.waitingForKeyFrame = true;
+        }
+        else {
+            decoder = new window.AudioDecoder({
+                output: (data) => {
+                    writer.write(data);
+                    data.close();
+                },
+                error: (e) => console.error("AudioDecoder error", e)
+            });
+            decoder.configure({
+                codec: 'opus',
+                sampleRate: 48000,
+                numberOfChannels: 1
+            });
+        }
+        // Attach a method to the track object or return a controller?
+        // We will just return the track, but we need a way to feed data into the decoder.
+        // We can monkey-patch the track or store it in a map in PeerConnection.
+        generator.feed = (data) => {
+            if (decoder.state === 'closed')
+                return;
+            // Verify Magic
+            if (data.byteLength < 1 || data[0] !== 0x77) {
+                console.error("[MediaTransport] Invalid magic byte in media stream! Dropping packet.");
+                return;
+            }
+            if (kind === 'video') {
+                // Parse
+                const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+                const timestamp = Number(view.getBigInt64(1, false));
+                const isKey = view.getUint8(9) === 1;
+                const seq = view.getUint16(10, false);
+                const chunkData = data.slice(12);
+                // Sequence Check
+                if (expectedSeq !== null) {
+                    if (seq !== expectedSeq) {
+                        console.warn(`[MediaTransport] Sequence Mismatch! Expected ${expectedSeq}, got ${seq}. Dropping and requesting PLI.`);
+                        decoder.waitingForKeyFrame = true;
+                        if (onKeyFrameRequest)
+                            onKeyFrameRequest();
+                        // We also reset expectedSeq to this new one + 1? 
+                        // No, we better wait for KeyFrame.
+                        // But we must update expectedSeq to avoid infinite loops if the stream just continues.
+                        expectedSeq = (seq + 1) % 65536;
+                        return;
+                    }
+                }
+                expectedSeq = (seq + 1) % 65536;
+                const chunk = new window.EncodedVideoChunk({
+                    type: isKey ? 'key' : 'delta',
+                    timestamp: timestamp,
+                    data: chunkData
+                });
+                if (decoder.state === 'configured' && !isKey && decoder.waitingForKeyFrame !== false) {
+                    // Drop delta frames until we get a keyframe
+                    const now = Date.now();
+                    if (now - lastPli > 1000) {
+                        console.log("[MediaTransport] Dropping delta frame, waiting for key frame. Requesting PLI.");
+                        if (onKeyFrameRequest)
+                            onKeyFrameRequest();
+                        lastPli = now;
+                    }
+                    return;
+                }
+                if (isKey) {
+                    decoder.waitingForKeyFrame = false;
+                }
+                try {
+                    decoder.decode(chunk);
+                }
+                catch (e) {
+                    console.error("[MediaTransport] Decode error:", e);
+                }
+            }
+            else {
+                const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+                const timestamp = Number(view.getBigInt64(1, false));
+                const chunkData = data.slice(9);
+                const chunk = new window.EncodedAudioChunk({
+                    type: 'key', // Audio usually all key frames or dependent? Opus is complicated.
+                    timestamp: timestamp,
+                    data: chunkData
+                });
+                decoder.decode(chunk);
+            }
+        };
+        return generator;
+    }
+}

package/dist/api/PlutoPeerConnection.d.ts

@@ -0,0 +1,50 @@
+import { Client } from '../core/Client';
+import { Connection } from '../core/Connection';
+export declare class PlutoPeerConnection extends EventTarget {
+    static defaultClient: Client | null;
+    static setDefaultClient(client: Client): void;
+    onicecandidate: ((ev: RTCPeerConnectionIceEvent) => any) | null;
+    oniceconnectionstatechange: ((ev: Event) => any) | null;
+    ontrack: ((ev: RTCTrackEvent) => any) | null;
+    onsignalingstatechange: ((ev: Event) => any) | null;
+    connectionState: RTCPeerConnectionState;
+    iceConnectionState: RTCIceConnectionState;
+    signalingState: RTCSignalingState;
+    localDescription: RTCSessionDescription | null;
+    remoteDescription: RTCSessionDescription | null;
+    private client;
+    private connection;
+    private get useMoq();
+    get transportInfo(): {
+        signaling: string;
+        media: string;
+    };
+    constructor(configuration?: RTCConfiguration, clientInstance?: Client);
+    createOffer(options?: RTCOfferOptions): Promise<RTCSessionDescriptionInit>;
+    createAnswer(options?: RTCAnswerOptions): Promise<RTCSessionDescriptionInit>;
+    setLocalDescription(desc: RTCSessionDescriptionInit): Promise<void>;
+    setRemoteDescription(desc: RTCSessionDescriptionInit): Promise<void>;
+    addIceCandidate(candidate: RTCIceCandidateInit | RTCIceCandidate): Promise<void>;
+    /**
+     * Manually provide an existing connection (e.g. from an incoming connection listener)
+     */
+    private bufferTracks;
+    handleIncomingConnection(connection: Connection): Promise<void>;
+    private receivers;
+    private setupHooks;
+    private handleLegacyMedia;
+    private moqDecoders;
+    private moqGenerators;
+    private handleMoQMedia;
+    private handleMoQData;
+    private fireTrackEvent;
+    addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender;
+    private mediaSenders;
+    private startIrohStream;
+    private startMoQStream;
+    createDataChannel(label: string): RTCDataChannel;
+    sendData(data: any): void;
+    private connect;
+    close(): void;
+    private updateState;
+}