@soulcraft/sdk 1.1.0 → 1.2.0

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"}