@soulcraft/sdk 1.0.0 → 1.2.0

package/dist/modules/hall/browser.js

@@ -0,0 +1,265 @@
+/**
+ * @module modules/hall/browser
+ * @description Browser-side Hall room client — joins a WebRTC room via a session token.
+ *
+ * `joinHallRoom` is the browser entry point for Hall real-time communication.
+ * It opens a WebSocket to the Hall signaling endpoint, negotiates a WebRTC peer
+ * connection via offer/answer/ICE, and returns a `HallRoomHandle` with typed events
+ * for tracks, transcripts, concept mentions, and room lifecycle.
+ *
+ * **Auth model:** The browser never sees the product's shared secret. The product
+ * backend mints a short-lived HMAC session token (via `sdk.hall.createSessionToken`)
+ * and passes it to the browser. The browser passes the token to `joinHallRoom` — that
+ * is the only browser credential.
+ *
+ * This module has no server-only dependencies and is safe to bundle for the browser.
+ * It does require `RTCPeerConnection` and `WebSocket` to be available (standard in
+ * all modern browsers; not available in Node.js without polyfills).
+ *
+ * @example
+ * ```typescript
+ * import { joinHallRoom } from '@soulcraft/sdk/client'
+ *
+ * // 1. Get token from product backend:
+ * const { token, hallUrl } = await fetch('/api/session/join').then(r => r.json())
+ *
+ * // 2. Get camera + mic:
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
+ *
+ * // 3. Join room:
+ * const room = await joinHallRoom({ token, hallUrl })
+ * room.addStream(stream)
+ *
+ * // 4. Handle events:
+ * room.on('trackAdded', ({ peerId, streams }) => {
+ *   document.getElementById(`video-${peerId}`).srcObject = streams[0]
+ * })
+ * room.on('transcript', ({ peerId, text, isFinal }) => {
+ *   if (isFinal) appendCaption(peerId, text)
+ * })
+ * room.on('conceptMention', ({ nodeId, confidence }) => pulseGraphNode(nodeId, confidence))
+ *
+ * // 5. On leave:
+ * room.close()
+ * ```
+ */
+class HallRoomHandleImpl {
+    roomId;
+    peerId;
+    #listeners = {
+        transcript: new Set(),
+        conceptMention: new Set(),
+        relationProposed: new Set(),
+        speakerChanged: new Set(),
+        peerJoined: new Set(),
+        peerLeft: new Set(),
+        trackAdded: new Set(),
+        trackRemoved: new Set(),
+        closed: new Set(),
+        error: new Set(),
+    };
+    #pc;
+    #ws;
+    constructor(roomId, peerId, pc, ws) {
+        this.roomId = roomId;
+        this.peerId = peerId;
+        this.#pc = pc;
+        this.#ws = ws;
+    }
+    on(event, listener) {
+        ;
+        this.#listeners[event].add(listener);
+        return this;
+    }
+    off(event, listener) {
+        ;
+        this.#listeners[event].delete(listener);
+        return this;
+    }
+    addStream(stream) {
+        for (const track of stream.getTracks()) {
+            this.#pc.addTrack(track, stream);
+        }
+    }
+    close() {
+        this.#ws.close(1000, 'peer leaving');
+        this.#pc.close();
+    }
+    /** @internal */
+    _dispatch(event, payload) {
+        for (const listener of this.#listeners[event]) {
+            try {
+                listener(payload);
+            }
+            catch (e) {
+                console.error(`[Hall] uncaught error in room '${this.roomId}' ${event} listener:`, e);
+            }
+        }
+    }
+}
+// ─── joinHallRoom ─────────────────────────────────────────────────────────────
+/**
+ * Join a Hall room from the browser using a session token.
+ *
+ * Opens a WebSocket to `{hallUrl}/ws/session/{token}`, creates an `RTCPeerConnection`,
+ * performs the offer/answer/ICE exchange, and resolves once the peer connection reaches
+ * `connected` state. Returns a {@link HallRoomHandle} with typed events.
+ *
+ * @param options - Token, Hall URL, and optional ICE server overrides.
+ * @returns A connected `HallRoomHandle`.
+ * @throws {Error} If the signaling handshake fails or the connection times out.
+ *
+ * @example
+ * ```typescript
+ * const room = await joinHallRoom({ token, hallUrl: 'wss://hall.soulcraft.com' })
+ * room.addStream(localStream)
+ * room.on('trackAdded', ({ peerId, streams }) => renderVideo(peerId, streams[0]))
+ * room.on('transcript', ({ text, isFinal }) => { if (isFinal) showCaption(text) })
+ * ```
+ */
+export async function joinHallRoom(options) {
+    const { token, hallUrl, iceServers = [] } = options;
+    const signalingUrl = `${hallUrl}/ws/session/${encodeURIComponent(token)}`;
+    // The Hall server sends TURN credentials in the first message after the WebSocket opens.
+    // We resolve ICE servers from that before creating the RTCPeerConnection.
+    const ws = new WebSocket(signalingUrl);
+    const handle = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error('Hall: signaling connection timed out after 30s'));
+        }, 30_000);
+        ws.onerror = () => {
+            clearTimeout(timeout);
+            reject(new Error('Hall: WebSocket error during signaling'));
+        };
+        ws.onopen = async () => {
+            // Create the peer connection. Hall's TURN server handles NAT traversal —
+            // the signaling 'answer' message from Hall includes ICE candidates.
+            const pc = new RTCPeerConnection({
+                iceServers: [
+                    // Hall's in-process TURN is always available.
+                    // The session token encodes the TURN credentials — Hall provides them via the ws.
+                    { urls: `${hallUrl.replace('wss://', 'turn:').replace('ws://', 'turn:')}:3478` },
+                    ...iceServers,
+                ],
+            });
+            // Send ICE candidates to Hall as they are gathered.
+            pc.onicecandidate = (ev) => {
+                if (ev.candidate) {
+                    ws.send(JSON.stringify({ type: 'ice', candidate: JSON.stringify(ev.candidate) }));
+                }
+            };
+            // Create and send SDP offer.
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+            ws.send(JSON.stringify({ type: 'offer', sdp: offer.sdp }));
+            ws.onmessage = async (ev) => {
+                let msg;
+                try {
+                    msg = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === 'answer') {
+                    await pc.setRemoteDescription({ type: 'answer', sdp: msg.sdp });
+                    return;
+                }
+                if (msg.type === 'ice') {
+                    try {
+                        await pc.addIceCandidate(JSON.parse(msg.candidate));
+                    }
+                    catch {
+                        // Stale ICE candidates are harmless to ignore.
+                    }
+                    return;
+                }
+                if (msg.type === 'error') {
+                    clearTimeout(timeout);
+                    ws.close();
+                    pc.close();
+                    reject(new Error(`Hall signaling error: ${msg.message}`));
+                    return;
+                }
+                // The peer connection is considered "ready" once we have a remote description.
+                // Resolve the handle at this point so event listeners can be attached.
+                // We defer the roomId/peerId extraction to after the connection resolves.
+                // Hall sends peerJoined as the first room event after ICE completes.
+                if (!roomHandleRef)
+                    return;
+                routeSignalingEvent(roomHandleRef, msg);
+            };
+            // Resolve once connected. Track events before connection is established are
+            // buffered by the browser's RTCPeerConnection — addTrack after setRemoteDescription.
+            pc.onconnectionstatechange = () => {
+                if (pc.connectionState === 'connected' && !roomHandleRef) {
+                    // roomId and peerId are decoded from the token by Hall and sent in peerJoined.
+                    // We use placeholders here; they are filled in by the first peerJoined event.
+                    const h = new HallRoomHandleImpl('', '', pc, ws);
+                    roomHandleRef = h;
+                    clearTimeout(timeout);
+                    resolve(h);
+                }
+                if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
+                    if (!roomHandleRef) {
+                        clearTimeout(timeout);
+                        reject(new Error(`Hall: WebRTC connection ${pc.connectionState}`));
+                    }
+                }
+            };
+            // Wire track events.
+            pc.ontrack = (ev) => {
+                if (!roomHandleRef)
+                    return;
+                roomHandleRef._dispatch('trackAdded', {
+                    peerId: 'remote', // refined by peerJoined
+                    track: ev.track,
+                    streams: ev.streams,
+                });
+                ev.track.onended = () => {
+                    roomHandleRef?._dispatch('trackRemoved', { peerId: 'remote', track: ev.track });
+                };
+            };
+        };
+        let roomHandleRef = null;
+        ws.onclose = (ev) => {
+            if (roomHandleRef) {
+                if (ev.code !== 1000) {
+                    roomHandleRef._dispatch('error', { message: `Hall WebSocket closed: ${ev.reason || ev.code}` });
+                }
+                roomHandleRef._dispatch('closed', { roomId: roomHandleRef.roomId });
+            }
+        };
+    });
+    return handle;
+}
+// ─── Signaling event router ───────────────────────────────────────────────────
+function routeSignalingEvent(handle, msg) {
+    switch (msg.type) {
+        case 'transcript':
+            handle._dispatch('transcript', msg);
+            break;
+        case 'conceptMention':
+            handle._dispatch('conceptMention', msg);
+            break;
+        case 'relationProposed':
+            handle._dispatch('relationProposed', msg);
+            break;
+        case 'speaker_changed':
+            handle._dispatch('speakerChanged', { roomId: msg.roomId, peerId: msg.speakerId });
+            break;
+        case 'peerJoined':
+            handle._dispatch('peerJoined', msg);
+            break;
+        case 'peerLeft':
+            handle._dispatch('peerLeft', msg);
+            break;
+        case 'roomClosed':
+            handle._dispatch('closed', { roomId: msg.roomId });
+            break;
+        case 'error':
+            handle._dispatch('error', { message: msg.message });
+            break;
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/modules/hall/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../src/modules/hall/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AA4DH,MAAM,kBAAkB;IACb,MAAM,CAAQ;IACd,MAAM,CAAQ;IAEd,UAAU,GAAsB;QACvC,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,cAAc,EAAE,IAAI,GAAG,EAAE;QACzB,gBAAgB,EAAE,IAAI,GAAG,EAAE;QAC3B,cAAc,EAAE,IAAI,GAAG,EAAE;QACzB,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,QAAQ,EAAE,IAAI,GAAG,EAAE;QACnB,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,YAAY,EAAE,IAAI,GAAG,EAAE;QACvB,MAAM,EAAE,IAAI,GAAG,EAAE;QACjB,KAAK,EAAE,IAAI,GAAG,EAAE;KACjB,CAAA;IAEQ,GAAG,CAAmB;IACtB,GAAG,CAAW;IAEvB,YAAY,MAAc,EAAE,MAAc,EAAE,EAAqB,EAAE,EAAa;QAC9E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;QACb,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;IACf,CAAC;IAED,EAAE,CACA,KAAQ,EACR,QAAiD;QAEjD,CAAC;QAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAkD,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACvF,OAAO,IAAI,CAAA;IACb,CAAC;IAED,GAAG,CACD,KAAQ,EACR,QAAiD;QAEjD,CAAC;QAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAkD,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC1F,OAAO,IAAI,CAAA;IACb,CAAC;IAED,SAAS,CAAC,MAAmB;QAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,CAAA;QACpC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,gBAAgB;IAChB,SAAS,CACP,KAAQ,EACR,OAAgC;QAEhC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAiD,EAAE,CAAC;YAC9F,IAAI,CAAC;gBACH,QAAQ,CAAC,OAAO,CAAC,CAAA;YACnB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,kCAAkC,IAAI,CAAC,MAAM,KAAK,KAAK,YAAY,EAAE,CAAC,CAAC,CAAA;YACvF,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAA4B;IAC7D,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,GAAG,EAAE,EAAE,GAAG,OAAO,CAAA;IAEnD,MAAM,YAAY,GAAG,GAAG,OAAO,eAAe,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAA;IAEzE,yFAAyF;IACzF,0EAA0E;IAC1E,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,YAAY,CAAC,CAAA;IAEtC,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACvE,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,EAAE,CAAC,KAAK,EAAE,CAAA;YACV,MAAM,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC,CAAA;QACrE,CAAC,EAAE,MAAM,CAAC,CAAA;QAEV,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE;YAChB,YAAY,CAAC,OAAO,CAAC,CAAA;YACrB,MAAM,CAAC,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,CAAA;QAC7D,CAAC,CAAA;QAED,EAAE,CAAC,MAAM,GAAG,KAAK,IAAI,EAAE;YACrB,yEAAyE;YACzE,oEAAoE;YACpE,MAAM,EAAE,GAAG,IAAI,iBAAiB,CAAC;gBAC/B,UAAU,EAAE;oBACV,8CAA8C;oBAC9C,kFAAkF;oBAClF,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE;oBAChF,GAAG,UAAU;iBACd;aACF,CAAC,CAAA;YAEF,oDAAoD;YACpD,EAAE,CAAC,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE;gBACzB,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;oBACjB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAA;gBACnF,CAAC;YACH,CAAC,CAAA;YAED,6BAA6B;YAC7B,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,WAAW,EAAE,CAAA;YACpC,MAAM,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAA;YACnC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;YAE1D,EAAE,CAAC,SAAS,GAAG,KAAK,EAAE,EAAE,EAAE,EAAE;gBAC1B,IAAI,GAAqB,CAAA;gBACzB,IAAI,CAAC;oBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAc,CAAqB,CAAA;gBACzD,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAM;gBACR,CAAC;gBAED,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC1B,MAAM,EAAE,CAAC,oBAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;oBAC/D,OAAM;gBACR,CAAC;gBAED,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;oBACvB,IAAI,CAAC;wBACH,MAAM,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAwB,CAAC,CAAA;oBAC5E,CAAC;oBAAC,MAAM,CAAC;wBACP,+CAA+C;oBACjD,CAAC;oBACD,OAAM;gBACR,CAAC;gBAED,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBACzB,YAAY,CAAC,OAAO,CAAC,CAAA;oBACrB,EAAE,CAAC,KAAK,EAAE,CAAA;oBACV,EAAE,CAAC,KAAK,EAAE,CAAA;oBACV,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;oBACzD,OAAM;gBACR,CAAC;gBAED,+EAA+E;gBAC/E,uEAAuE;gBACvE,0EAA0E;gBAC1E,qEAAqE;gBACrE,IAAI,CAAC,aAAa;oBAAE,OAAM;gBAC1B,mBAAmB,CAAC,aAAa,EAAE,GAAG,CAAC,CAAA;YACzC,CAAC,CAAA;YAED,4EAA4E;YAC5E,qFAAqF;YACrF,EAAE,CAAC,uBAAuB,GAAG,GAAG,EAAE;gBAChC,IAAI,EAAE,CAAC,eAAe,KAAK,WAAW,IAAI,CAAC,aAAa,EAAE,CAAC;oBACzD,+EAA+E;oBAC/E,8EAA8E;oBAC9E,MAAM,CAAC,GAAG,IAAI,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;oBAChD,aAAa,GAAG,CAAC,CAAA;oBACjB,YAAY,CAAC,OAAO,CAAC,CAAA;oBACrB,OAAO,CAAC,CAAC,CAAC,CAAA;gBACZ,CAAC;gBACD,IAAI,EAAE,CAAC,eAAe,KAAK,QAAQ,IAAI,EAAE,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC;oBACvE,IAAI,CAAC,aAAa,EAAE,CAAC;wBACnB,YAAY,CAAC,OAAO,CAAC,CAAA;wBACrB,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC,CAAA;oBACpE,CAAC;gBACH,CAAC;YACH,CAAC,CAAA;YAED,qBAAqB;YACrB,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,EAAE,EAAE;gBAClB,IAAI,CAAC,aAAa;oBAAE,OAAM;gBAC1B,aAAa,CAAC,SAAS,CAAC,YAAY,EAAE;oBACpC,MAAM,EAAE,QAAQ,EAAE,wBAAwB;oBAC1C,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,OAAO,EAAE,EAAE,CAAC,OAAO;iBACpB,CAAC,CAAA;gBACF,EAAE,CAAC,KAAK,CAAC,OAAO,GAAG,GAAG,EAAE;oBACtB,aAAa,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAA;gBACjF,CAAC,CAAA;YACH,CAAC,CAAA;QACH,CAAC,CAAA;QAED,IAAI,aAAa,GAA8B,IAAI,CAAA;QAEnD,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,EAAE,EAAE;YAClB,IAAI,aAAa,EAAE,CAAC;gBAClB,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACrB,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;gBACjG,CAAC;gBACD,aAAa,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,CAAA;YACrE,CAAC;QACH,CAAC,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC;AAED,iFAAiF;AAEjF,SAAS,mBAAmB,CAAC,MAA0B,EAAE,GAAqB;IAC5E,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,YAAY;YACf,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,GAAiC,CAAC,CAAA;YACjE,MAAK;QACP,KAAK,gBAAgB;YACnB,MAAM,CAAC,SAAS,CAAC,gBAAgB,EAAE,GAAqC,CAAC,CAAA;YACzE,MAAK;QACP,KAAK,kBAAkB;YACrB,MAAM,CAAC,SAAS,CAAC,kBAAkB,EAAE,GAAuC,CAAC,CAAA;YAC7E,MAAK;QACP,KAAK,iBAAiB;YACpB,MAAM,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,SAAS,EAAyB,CAAC,CAAA;YACxG,MAAK;QACP,KAAK,YAAY;YACf,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,GAAiC,CAAC,CAAA;YACjE,MAAK;QACP,KAAK,UAAU;YACb,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,GAA+B,CAAC,CAAA;YAC7D,MAAK;QACP,KAAK,YAAY;YACf,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;YAClD,MAAK;QACP,KAAK,OAAO;YACV,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAA;YACnD,MAAK;IACT,CAAC;AACH,CAAC"}

package/dist/modules/hall/protocol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module modules/hall/protocol
+ * @description MessagePack encode/decode for Hall WebSocket frames.
+ *
+ * All Hall WebSocket frames are binary msgpack. The Rust server uses serde's
+ * `tag/content` encoding: `{ t: "messageType", d: { ...fields } }`.
+ *
+ * This module provides typed encode/decode functions that match the Rust
+ * protocol exactly. Runtime validation catches protocol drift early.
+ *
+ * @example
+ * ```typescript
+ * const bytes = encodeHallMessage({ t: 'createRoom', d: { roomId: 'abc', options: {} } })
+ * socket.send(bytes)
+ *
+ * socket.onmessage = (ev) => {
+ *   const msg = decodeHallMessage(ev.data)
+ *   if (msg.t === 'roomCreated') console.log(msg.d.sessionId)
+ * }
+ * ```
+ */
+import type { HallClientMessage, HallServerMessage } from './types.js';
+/**
+ * Encode a {@link HallClientMessage} to msgpack bytes for transmission over WebSocket.
+ *
+ * @param msg - The typed client message to encode.
+ * @returns Binary msgpack payload ready to send via `WebSocket.send()`.
+ */
+export declare function encodeHallMessage(msg: HallClientMessage): Uint8Array;
+/**
+ * Decode a msgpack binary frame received from the Hall server.
+ *
+ * @param data - Raw bytes from a WebSocket binary message (`ev.data`).
+ * @returns The decoded {@link HallServerMessage}.
+ * @throws {Error} If the bytes are not valid msgpack or the decoded value is
+ *   not a recognised server message object (missing `t` field).
+ */
+export declare function decodeHallMessage(data: ArrayBuffer | Uint8Array): HallServerMessage;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/modules/hall/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,iBAAiB,CAiBnF"}

package/dist/modules/hall/protocol.js

@@ -0,0 +1,52 @@
+/**
+ * @module modules/hall/protocol
+ * @description MessagePack encode/decode for Hall WebSocket frames.
+ *
+ * All Hall WebSocket frames are binary msgpack. The Rust server uses serde's
+ * `tag/content` encoding: `{ t: "messageType", d: { ...fields } }`.
+ *
+ * This module provides typed encode/decode functions that match the Rust
+ * protocol exactly. Runtime validation catches protocol drift early.
+ *
+ * @example
+ * ```typescript
+ * const bytes = encodeHallMessage({ t: 'createRoom', d: { roomId: 'abc', options: {} } })
+ * socket.send(bytes)
+ *
+ * socket.onmessage = (ev) => {
+ *   const msg = decodeHallMessage(ev.data)
+ *   if (msg.t === 'roomCreated') console.log(msg.d.sessionId)
+ * }
+ * ```
+ */
+import { encode, decode } from '@msgpack/msgpack';
+/**
+ * Encode a {@link HallClientMessage} to msgpack bytes for transmission over WebSocket.
+ *
+ * @param msg - The typed client message to encode.
+ * @returns Binary msgpack payload ready to send via `WebSocket.send()`.
+ */
+export function encodeHallMessage(msg) {
+    return encode(msg);
+}
+/**
+ * Decode a msgpack binary frame received from the Hall server.
+ *
+ * @param data - Raw bytes from a WebSocket binary message (`ev.data`).
+ * @returns The decoded {@link HallServerMessage}.
+ * @throws {Error} If the bytes are not valid msgpack or the decoded value is
+ *   not a recognised server message object (missing `t` field).
+ */
+export function decodeHallMessage(data) {
+    const raw = decode(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+    if (typeof raw !== 'object' ||
+        raw === null ||
+        !('t' in raw) ||
+        typeof raw.t !== 'string') {
+        throw new Error(`Invalid Hall message: expected object with string "t" field, got ${JSON.stringify(raw)}`);
+    }
+    // Trust the server to send well-formed messages — full schema validation
+    // would duplicate the Rust type definitions and add runtime cost.
+    return raw;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/modules/hall/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/modules/hall/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAGjD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAsB;IACtD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAA;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA8B;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,YAAY,WAAW,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAE7E,IACE,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;QACb,OAAQ,GAA+B,CAAC,CAAC,KAAK,QAAQ,EACtD,CAAC;QACD,MAAM,IAAI,KAAK,CACb,oEAAoE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAC1F,CAAA;IACH,CAAC;IAED,yEAAyE;IACzE,kEAAkE;IAClE,OAAO,GAAwB,CAAA;AACjC,CAAC"}

package/dist/modules/hall/server.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @module modules/hall/server
+ * @description Server-side Hall client — product backend to Hall server control plane.
+ *
+ * `HallClient` maintains a single authenticated WebSocket connection from the product
+ * backend to `hall.soulcraft.com`. All room management (createRoom, closeRoom, session
+ * tokens, recording) goes through this connection.
+ *
+ * This module is **server-only** — it uses WebSocket, reconnect timers, and the
+ * product shared secret, none of which should ever reach a browser bundle.
+ *
+ * Use `createHallModule(options)` from `@soulcraft/sdk/server` to get a fully wired
+ * `HallModule` instance. Direct use of `HallClient` is for advanced scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { createHallModule } from '@soulcraft/sdk/server'
+ *
+ * const hall = createHallModule({
+ *   url: process.env.HALL_URL!,
+ *   productName: 'academy',
+ *   secret: process.env.HALL_ACADEMY_SECRET!,
+ * })
+ * await hall.connect()
+ * const room = await hall.createRoom('cohort-123', { enableTranscription: true })
+ * room.on('transcript', (t) => console.log(t.text))
+ * const { token } = await hall.createSessionToken('cohort-123', 'user-456')
+ * ```
+ */
+import type { HallConnectionOptions, HallModule, HallRoom, HallRoomEvents, RoomOptions } from './types.js';
+type Listener<T> = (event: T) => void;
+/**
+ * Concrete implementation of the {@link HallRoom} interface.
+ *
+ * Stores per-event listener sets and provides a typed dispatch method called
+ * internally by `HallClient` when the server pushes room events.
+ */
+export declare class HallRoomImpl implements HallRoom {
+    #private;
+    readonly roomId: string;
+    readonly sessionId: string;
+    constructor(roomId: string, sessionId: string);
+    on<K extends keyof HallRoomEvents>(event: K, listener: Listener<HallRoomEvents[K]>): this;
+    off<K extends keyof HallRoomEvents>(event: K, listener: Listener<HallRoomEvents[K]>): this;
+    /** @internal Dispatches an incoming server event to all registered listeners. */
+    _dispatch<K extends keyof HallRoomEvents>(event: K, payload: HallRoomEvents[K]): void;
+}
+/**
+ * Product-backend WebSocket client for the Hall real-time communication server.
+ *
+ * Create one instance per product process. Maintains a single authenticated control-plane
+ * WebSocket to `hall.soulcraft.com`. All room management and event routing goes through
+ * this single connection — do not create multiple instances per product.
+ *
+ * Auto-reconnects on unexpected disconnect (configurable via `reconnectDelayMs`).
+ * In-flight promises are rejected on disconnect; register `onReconnect` to re-create rooms.
+ */
+export declare class HallClient implements HallModule {
+    #private;
+    readonly url: string;
+    /**
+     * @param options - Connection options: url, productName, secret, and optional reconnectDelayMs.
+     */
+    constructor(options: HallConnectionOptions);
+    /**
+     * Connect to the Hall server and authenticate with the product shared secret.
+     * Must be called once at startup before any other method.
+     *
+     * @returns Resolves when `authOk` is received from the server.
+     * @throws {Error} If auth fails or the WebSocket cannot connect.
+     */
+    connect(): Promise<void>;
+    /**
+     * Gracefully close all active rooms and disconnect from the Hall server.
+     * After calling this, the instance cannot be reconnected.
+     */
+    close(): Promise<void>;
+    /**
+     * Register a listener for unexpected disconnects (not triggered by `close()`).
+     * Use this to log the event and prepare to re-create rooms after reconnect.
+     *
+     * @param listener - Called with a human-readable reason string (e.g. `"code 1006"`).
+     */
+    onDisconnect(listener: (reason: string) => void): void;
+    /**
+     * Register a listener for successful reconnections.
+     * On reconnect, rooms from before the disconnect are gone — re-create them here.
+     *
+     * @param listener - Called with no arguments when the reconnect auth succeeds.
+     */
+    onReconnect(listener: () => void): void;
+    /**
+     * Create a new room on the Hall server.
+     *
+     * @param roomId - Unique room identifier (e.g. Brainy session entity ID).
+     * @param options - Room configuration: peer limit, transcription, recording, concept list.
+     * @returns The HallRoom handle — register event listeners on it immediately.
+     * @throws {Error} If a room with the same ID already exists or the server returns an error.
+     */
+    createRoom(roomId: string, options?: RoomOptions): Promise<HallRoomImpl>;
+    /**
+     * Close a room and disconnect all its peers.
+     *
+     * @param roomId - The room ID passed to `createRoom`.
+     * @throws {Error} If the server returns an error.
+     */
+    closeRoom(roomId: string): Promise<void>;
+    /**
+     * Return the IDs of all active rooms managed by this connection.
+     *
+     * @returns Array of room ID strings currently active on the server.
+     */
+    listRooms(): Promise<string[]>;
+    /**
+     * Return an active room handle by ID, or `undefined` if not found.
+     *
+     * @param roomId - The room ID passed to `createRoom`.
+     */
+    getRoom(roomId: string): HallRoomImpl | undefined;
+    /**
+     * Mint a short-lived HMAC session token for a browser peer.
+     * Pass `{ token, hallUrl }` to the browser — **never** the product secret.
+     *
+     * @param roomId - The room the browser peer will join.
+     * @param peerId - The peer's unique identifier (e.g. authenticated user ID).
+     * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @returns `{ token, expiresAt }` — send `token` and `this.url` to the browser.
+     */
+    createSessionToken(roomId: string, peerId: string, ttlSecs?: number): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Start per-track MKV recording for an active room.
+     * The room emits `recordingManifest` when `stopRecording` is called.
+     *
+     * @param roomId - The room to start recording.
+     */
+    startRecording(roomId: string): Promise<void>;
+    /**
+     * Stop recording for a room. Hall writes track files and emits `recordingManifest`
+     * on the room handle with absolute paths to the recorded MKV files.
+     *
+     * @param roomId - The room to stop recording.
+     */
+    stopRecording(roomId: string): Promise<void>;
+}
+/**
+ * Create a server-mode Hall module that connects to the Hall standalone server.
+ *
+ * Returns a `HallModule` backed by a `HallClient`. Call `connect()` once at startup.
+ * In typical server mode SDK usage, `createSDK` calls this automatically when
+ * `hall` options are provided in `ServerSDKOptions`.
+ *
+ * @param options - Connection options: url, productName, secret, reconnectDelayMs.
+ * @returns A `HallModule` instance (not yet connected — call `module.connect()`).
+ *
+ * @example
+ * ```typescript
+ * import { createHallModule } from '@soulcraft/sdk/server'
+ *
+ * const hall = createHallModule({
+ *   url: process.env.HALL_URL!,
+ *   productName: 'academy',
+ *   secret: process.env.HALL_ACADEMY_SECRET!,
+ * })
+ * await hall.connect()
+ * ```
+ */
+export declare function createHallModule(options: HallConnectionOptions): HallModule;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/modules/hall/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,QAAQ,EACR,cAAc,EAEd,WAAW,EAQZ,MAAM,YAAY,CAAA;AAInB,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;AAGrC;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,QAAQ;;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAad,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAK7C,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAKzF,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAK1F,iFAAiF;IACjF,SAAS,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;CAStF;AAWD;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,UAAU;;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAwBpB;;OAEG;gBACS,OAAO,EAAE,qBAAqB;IAS1C;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAItD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAMvC;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5E;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ9B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD;;;;;;;;OAQG;IACH,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAShD;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAyN7C;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAE3E"}