@soulcraft/sdk 1.0.0

package/dist/server/create-sdk.js

@@ -0,0 +1,125 @@
+/**
+ * @module server/create-sdk
+ * @description `createSDK` factory for server-mode @soulcraft/sdk.
+ *
+ * Assembles a complete `SoulcraftSDK` instance from a live Brainy instance.
+ * In server mode the SDK uses the {@link LocalTransport} — zero overhead, no
+ * serialization, in-process method dispatch directly into the Brainy instance.
+ *
+ * The returned SDK object is scoped to a single Brainy instance. In a typical
+ * server request handler the caller resolves the correct Brainy instance from a
+ * {@link BrainyInstancePool} and then calls `createSDK({ brain })`. A new SDK
+ * object per request is cheap — it's a thin wrapper, not a connection.
+ *
+ * @example Workshop request handler
+ * ```typescript
+ * import { BrainyInstancePool, createSDK } from '@soulcraft/sdk/server'
+ *
+ * const pool = new BrainyInstancePool({ storage: 'filesystem', dataPath: './data', strategy: 'per-user' })
+ *
+ * app.get('/api/inventory', requireAuth, async (c) => {
+ *   const user = c.get('user')!
+ *   const brain = await pool.forUser(user.emailHash, 'main')
+ *   const sdk = createSDK({ brain })
+ *
+ *   const items = await sdk.brainy.find({ query: 'inventory items', type: 'Product' })
+ *   const readme = await sdk.vfs.readFile('/projects/my-project/README.md')
+ *   return c.json({ items })
+ * })
+ * ```
+ */
+import { LocalTransport } from '../transports/local.js';
+import { createBrainyProxy } from '../modules/brainy/proxy.js';
+import { createEventsModule } from '../modules/events/index.js';
+import { createAiModule } from '../modules/ai/index.js';
+import { createSkillsModule } from '../modules/skills/index.js';
+import { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/auth.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a server-mode `SoulcraftSDK` wrapping a live Brainy instance.
+ *
+ * All `sdk.brainy.*` and `sdk.vfs.*` calls are dispatched in-process with zero
+ * serialization overhead via {@link LocalTransport}.
+ *
+ * `sdk.ai.*` calls go directly to the Anthropic API (requires `ANTHROPIC_API_KEY`).
+ * `sdk.skills.*` reads from the Brainy VFS and falls back to `@soulcraft/kits`.
+ * `sdk.events` is a local EventEmitter — events do not cross process boundaries.
+ *
+ * @param options - SDK creation options.
+ * @returns A fully assembled `SoulcraftSDK` instance.
+ *
+ * @example
+ * ```typescript
+ * const brain = await pool.forUser(user.emailHash, workspaceId)
+ * const sdk = createSDK({ brain })
+ *
+ * const results = await sdk.brainy.find({ query: 'candle inventory' })
+ * const readme = await sdk.vfs.readFile('/projects/README.md')
+ * await sdk.events.emit('kit:session-completed', { userId, sessionId, kitId })
+ * ```
+ */
+export function createSDK(options) {
+    const { brain } = options;
+    const transport = new LocalTransport(brain);
+    const brainyProxy = createBrainyProxy(transport);
+    // VFS and versions are sub-APIs of Brainy, accessed via the same proxy.
+    // The proxy handles dot-separated paths: sdk.vfs.readFile → 'vfs.readFile'
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const vfs = brainyProxy.vfs;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const versions = brainyProxy.versions;
+    const events = createEventsModule();
+    const ai = createAiModule();
+    const skills = createSkillsModule(brain);
+    const auth = {
+        verifyToken: (token, secret) => verifyCapabilityToken(token, secret),
+        createToken: (opts) => createCapabilityToken(opts),
+    };
+    return {
+        brainy: brainyProxy,
+        vfs,
+        versions,
+        auth,
+        events,
+        ai,
+        skills,
+        // Stubs for unimplemented modules — will throw if called
+        license: _unimplementedModule('license'),
+        kits: _unimplementedModule('kits'),
+        formats: _unimplementedModule('formats'),
+        billing: _unimplementedModule('billing'),
+        notifications: _unimplementedModule('notifications'),
+        async shutdown() {
+            await brain.flush();
+        },
+        async flush(scopeKey) {
+            // Local transport — the caller owns the brain, so we flush directly.
+            // The scopeKey is informational only; the brain is already resolved.
+            void scopeKey;
+            await brain.flush();
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates a Proxy that throws a descriptive error for any property access
+ * on an unimplemented SDK module. This makes missing modules fail fast and
+ * informatively rather than silently returning undefined.
+ *
+ * @param moduleName - The module name shown in the error message.
+ * @returns A Proxy that throws on any property access.
+ */
+function _unimplementedModule(moduleName) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            throw new Error(`sdk.${moduleName}.${String(prop)} is not yet implemented. ` +
+                `The '${moduleName}' module is planned for a future SDK release. ` +
+                `See docs/ADR-001-sdk-design.md for the implementation roadmap.`);
+        },
+    });
+}
+//# sourceMappingURL=create-sdk.js.map

package/dist/server/create-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-sdk.js","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAsBxF,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEzB,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,WAAW,GAAG,iBAAiB,CAAC,SAAS,CAAoB,CAAA;IAEnE,wEAAwE;IACxE,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,GAAG,GAAI,WAAmB,CAAC,GAAgB,CAAA;IACjD,8DAA8D;IAC9D,MAAM,QAAQ,GAAI,WAAmB,CAAC,QAA0B,CAAA;IAEhE,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,EAAE,GAAG,cAAc,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAExC,MAAM,IAAI,GAAe;QACvB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC;QACpE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC;KACnD,CAAA;IAED,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,GAAG;QACH,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,EAAE;QACF,MAAM;QAEN,yDAAyD;QACzD,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC;QAClC,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC;QACxC,aAAa,EAAE,oBAAoB,CAAC,eAAe,CAAC;QAEpD,KAAK,CAAC,QAAQ;YACZ,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAgB;YAC1B,qEAAqE;YACrE,qEAAqE;YACrE,KAAK,QAAQ,CAAA;YACb,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,UAAkB;IAC9C,OAAO,IAAI,KAAK,CAAC,EAA6B,EAAE;QAC9C,GAAG,CAAC,OAAO,EAAE,IAAqB;YAChC,MAAM,IAAI,KAAK,CACb,OAAO,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,2BAA2B;gBAC5D,QAAQ,UAAU,gDAAgD;gBAClE,gEAAgE,CACjE,CAAA;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/server/hall-handlers.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @module server/hall-handlers
+ * @description Factory functions for mounting Hall WebRTC signaling over WebSocket.
+ *
+ * Hall uses a lightweight JSON signaling protocol over WebSocket:
+ *
+ *   Client → Server:
+ *     { type: 'offer',  sdp: string }              — SDP offer (first message from peer)
+ *     { type: 'ice',    candidate: string }         — ICE candidate trickle
+ *     { type: 'data',   channel: string, data: number[] }  — data channel message
+ *     { type: 'leave' }                             — graceful peer disconnect
+ *
+ *   Server → Client:
+ *     { type: 'answer', sdp: string }               — SDP answer
+ *     { type: 'ice',    candidate: string }          — ICE candidate from SFU
+ *     { type: 'speaker_changed', speakerId: string }
+ *     { type: 'concept_mention', ...ConceptEvent }
+ *     { type: 'relation_proposed', ...RelationProposedEvent }
+ *     { type: 'transcript', peerId, text, isFinal, sessionMs }
+ *     { type: 'attention', ...AttentionEvent }
+ *     { type: 'track_added', peerId, trackId, kind }
+ *     { type: 'track_removed', peerId, trackId }
+ *     { type: 'error', message: string }
+ *
+ * Products mount a single WebSocket route (e.g. `GET /api/hall/rooms/:roomId/signal`)
+ * and delegate to the handler returned by createHallRoomHandler().
+ *
+ * @example Hono mounting
+ * ```typescript
+ * import { createHallRoomHandler } from '@soulcraft/sdk/server'
+ *
+ * const hallHandler = createHallRoomHandler({
+ *   server: hallServer,
+ *   authenticate: async (req) => getSessionUser(req),
+ *   resolvePeerId: (req, user) => (user as { id: string }).id,
+ *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
+ * })
+ *
+ * app.get('/api/hall/rooms/:roomId/signal', upgradeWebSocket((c) => {
+ *   const session = await hallHandler.handleUpgrade(c.req.raw)
+ *   if (!session) return { onClose: () => {} }
+ *   return {
+ *     onMessage: (event, ws) => hallHandler.handleMessage(session, event.data as string, (m) => ws.send(m)),
+ *     onClose: () => hallHandler.handleClose(session),
+ *   }
+ * }))
+ * ```
+ */
+import type { HallServer, Room } from '@soulcraft/hall';
+/**
+ * @description An active peer connection managed by the Hall signaling handler.
+ * Returned by handleUpgrade() and passed to every subsequent call.
+ */
+export interface HallSession {
+    /** The authenticated peer ID (e.g. user ID). */
+    readonly peerId: string;
+    /** The room this peer is joining. */
+    readonly room: Room;
+    /** Whether the peer has completed the SDP offer/answer handshake. */
+    joined: boolean;
+}
+/**
+ * @description Configuration for createHallRoomHandler().
+ */
+export interface HallRoomHandlerConfig {
+    /**
+     * The running HallServer instance to use for room management.
+     */
+    server: HallServer;
+    /**
+     * Authenticates an incoming WebSocket upgrade request.
+     * Return the authenticated user object (any shape), or null/undefined to reject.
+     * @param request - The HTTP upgrade request.
+     * @returns Authenticated user or null/undefined.
+     */
+    authenticate(request: Request): Promise<unknown> | unknown;
+    /**
+     * Derives the peer ID from the request and the authenticated user.
+     * @param request - The HTTP upgrade request.
+     * @param user - The result of authenticate().
+     * @returns The peer ID string (e.g. user.id, session.userId).
+     */
+    resolvePeerId(request: Request, user: unknown): string;
+    /**
+     * Derives the room ID from the request.
+     * @param request - The HTTP upgrade request.
+     * @returns The room ID string (e.g. from URL path parameter).
+     */
+    resolveRoomId(request: Request): string;
+    /**
+     * Optional room options applied when the room does not already exist.
+     * @param request - The HTTP upgrade request.
+     * @param user - The authenticated user.
+     * @returns RoomOptions or undefined to use defaults.
+     */
+    roomOptions?(request: Request, user: unknown): import('@soulcraft/hall').RoomOptions | undefined;
+}
+/**
+ * @description The object returned by createHallRoomHandler(). Products pass incoming
+ * WebSocket connections through this handler for complete Hall signaling management.
+ */
+export interface HallRoomHandler {
+    /**
+     * Authenticates the upgrade request and resolves the room/peer. Call this when
+     * the WebSocket connection is established.
+     * @param request - The HTTP upgrade request.
+     * @returns A HallSession if authentication succeeded, or null to reject.
+     */
+    handleUpgrade(request: Request): Promise<HallSession | null>;
+    /**
+     * Processes an incoming signaling message from a peer.
+     * @param session - The HallSession returned by handleUpgrade().
+     * @param data - Raw JSON string from the WebSocket message event.
+     * @param send - Callback to send a JSON string back to this peer's client.
+     */
+    handleMessage(session: HallSession, data: string, send: (message: string) => void): Promise<void>;
+    /**
+     * Cleans up when a peer disconnects. Always call this on WebSocket close/error.
+     * @param session - The HallSession to clean up.
+     */
+    handleClose(session: HallSession): Promise<void>;
+}
+/**
+ * @description TURN credential options for generateTurnCredentials().
+ */
+export interface TurnCredentialOptions {
+    /** The HMAC-SHA1 secret shared between this server and the TURN server. */
+    secret: string;
+    /** Peer/user identifier embedded in the credential username. */
+    peerId: string;
+    /** Credential TTL in seconds (default: 86400 — 24 hours). */
+    ttlSeconds?: number;
+}
+/**
+ * @description Time-limited TURN credentials for a peer, suitable for passing to
+ * RTCPeerConnection as iceServers configuration.
+ */
+export interface TurnCredentials {
+    /** Username in the form `{expiryTimestamp}:{peerId}`. */
+    username: string;
+    /** HMAC-SHA1 password derived from the shared secret and username. */
+    password: string;
+    /** Unix timestamp (seconds) when these credentials expire. */
+    expiresAt: number;
+}
+/**
+ * @description Generates time-limited TURN credentials using the TURN REST API
+ * authentication mechanism (RFC draft-uberti-behave-turn-rest-00).
+ *
+ * The TURN server must be configured with the same shared secret. Credentials
+ * expire after ttlSeconds and cannot be reused after that time.
+ *
+ * @param options - Secret, peer ID, and optional TTL.
+ * @returns Time-limited TURN credentials ready for RTCPeerConnection.iceServers.
+ *
+ * @example
+ * ```typescript
+ * const creds = generateTurnCredentials({
+ *   secret: process.env.TURN_SECRET!,
+ *   peerId: user.id,
+ *   ttlSeconds: 3600,
+ * })
+ * // Pass to client:
+ * return c.json({ turnUsername: creds.username, turnPassword: creds.password })
+ * ```
+ */
+export declare function generateTurnCredentials(options: TurnCredentialOptions): TurnCredentials;
+/**
+ * @description Factory that creates a framework-agnostic Hall WebRTC signaling
+ * handler. Products mount the returned handler at a WebSocket route and delegate
+ * upgrade, message, and close lifecycle events to it.
+ *
+ * The handler owns the full signaling lifecycle:
+ * - Authenticates the upgrade request
+ * - Resolves or creates the Room via HallServer
+ * - Forwards SDP offer → gets SDP answer from the NAPI SFU
+ * - Forwards ICE candidates in both directions
+ * - Wires Room events (transcript, concept_mention, relation_proposed, etc.) to the peer's send callback
+ * - Cleans up on disconnect
+ *
+ * @param config - Handler configuration.
+ * @returns A HallRoomHandler with handleUpgrade / handleMessage / handleClose.
+ *
+ * @example
+ * ```typescript
+ * const hallHandler = createHallRoomHandler({
+ *   server: hallServer,
+ *   authenticate: (req) => verifySession(req.headers.get('cookie') ?? ''),
+ *   resolvePeerId: (_req, user) => (user as { id: string }).id,
+ *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
+ * })
+ * ```
+ */
+export declare function createHallRoomHandler(config: HallRoomHandlerConfig): HallRoomHandler;
+//# sourceMappingURL=hall-handlers.d.ts.map

package/dist/server/hall-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hall-handlers.d.ts","sourceRoot":"","sources":["../../src/server/hall-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,IAAI,EAIL,MAAM,iBAAiB,CAAA;AAOxB;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAElB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAE1D;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IAEtD;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAA;IAEvC;;;;;OAKG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,WAAW,GAAG,SAAS,CAAA;CACjG;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAE5D;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjG;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAQvF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAqJpF"}

package/dist/server/hall-handlers.js

@@ -0,0 +1,239 @@
+/**
+ * @module server/hall-handlers
+ * @description Factory functions for mounting Hall WebRTC signaling over WebSocket.
+ *
+ * Hall uses a lightweight JSON signaling protocol over WebSocket:
+ *
+ *   Client → Server:
+ *     { type: 'offer',  sdp: string }              — SDP offer (first message from peer)
+ *     { type: 'ice',    candidate: string }         — ICE candidate trickle
+ *     { type: 'data',   channel: string, data: number[] }  — data channel message
+ *     { type: 'leave' }                             — graceful peer disconnect
+ *
+ *   Server → Client:
+ *     { type: 'answer', sdp: string }               — SDP answer
+ *     { type: 'ice',    candidate: string }          — ICE candidate from SFU
+ *     { type: 'speaker_changed', speakerId: string }
+ *     { type: 'concept_mention', ...ConceptEvent }
+ *     { type: 'relation_proposed', ...RelationProposedEvent }
+ *     { type: 'transcript', peerId, text, isFinal, sessionMs }
+ *     { type: 'attention', ...AttentionEvent }
+ *     { type: 'track_added', peerId, trackId, kind }
+ *     { type: 'track_removed', peerId, trackId }
+ *     { type: 'error', message: string }
+ *
+ * Products mount a single WebSocket route (e.g. `GET /api/hall/rooms/:roomId/signal`)
+ * and delegate to the handler returned by createHallRoomHandler().
+ *
+ * @example Hono mounting
+ * ```typescript
+ * import { createHallRoomHandler } from '@soulcraft/sdk/server'
+ *
+ * const hallHandler = createHallRoomHandler({
+ *   server: hallServer,
+ *   authenticate: async (req) => getSessionUser(req),
+ *   resolvePeerId: (req, user) => (user as { id: string }).id,
+ *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
+ * })
+ *
+ * app.get('/api/hall/rooms/:roomId/signal', upgradeWebSocket((c) => {
+ *   const session = await hallHandler.handleUpgrade(c.req.raw)
+ *   if (!session) return { onClose: () => {} }
+ *   return {
+ *     onMessage: (event, ws) => hallHandler.handleMessage(session, event.data as string, (m) => ws.send(m)),
+ *     onClose: () => hallHandler.handleClose(session),
+ *   }
+ * }))
+ * ```
+ */
+import { createHmac } from 'crypto';
+// ─────────────────────────────────────────────────────────────────────────────
+// generateTurnCredentials
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * @description Generates time-limited TURN credentials using the TURN REST API
+ * authentication mechanism (RFC draft-uberti-behave-turn-rest-00).
+ *
+ * The TURN server must be configured with the same shared secret. Credentials
+ * expire after ttlSeconds and cannot be reused after that time.
+ *
+ * @param options - Secret, peer ID, and optional TTL.
+ * @returns Time-limited TURN credentials ready for RTCPeerConnection.iceServers.
+ *
+ * @example
+ * ```typescript
+ * const creds = generateTurnCredentials({
+ *   secret: process.env.TURN_SECRET!,
+ *   peerId: user.id,
+ *   ttlSeconds: 3600,
+ * })
+ * // Pass to client:
+ * return c.json({ turnUsername: creds.username, turnPassword: creds.password })
+ * ```
+ */
+export function generateTurnCredentials(options) {
+    const ttl = options.ttlSeconds ?? 86_400;
+    const expiresAt = Math.floor(Date.now() / 1000) + ttl;
+    const username = `${expiresAt}:${options.peerId}`;
+    const password = createHmac('sha1', options.secret)
+        .update(username)
+        .digest('base64');
+    return { username, password, expiresAt };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// createHallRoomHandler
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * @description Factory that creates a framework-agnostic Hall WebRTC signaling
+ * handler. Products mount the returned handler at a WebSocket route and delegate
+ * upgrade, message, and close lifecycle events to it.
+ *
+ * The handler owns the full signaling lifecycle:
+ * - Authenticates the upgrade request
+ * - Resolves or creates the Room via HallServer
+ * - Forwards SDP offer → gets SDP answer from the NAPI SFU
+ * - Forwards ICE candidates in both directions
+ * - Wires Room events (transcript, concept_mention, relation_proposed, etc.) to the peer's send callback
+ * - Cleans up on disconnect
+ *
+ * @param config - Handler configuration.
+ * @returns A HallRoomHandler with handleUpgrade / handleMessage / handleClose.
+ *
+ * @example
+ * ```typescript
+ * const hallHandler = createHallRoomHandler({
+ *   server: hallServer,
+ *   authenticate: (req) => verifySession(req.headers.get('cookie') ?? ''),
+ *   resolvePeerId: (_req, user) => (user as { id: string }).id,
+ *   resolveRoomId: (req) => new URL(req.url).pathname.split('/').at(-2)!,
+ * })
+ * ```
+ */
+export function createHallRoomHandler(config) {
+    // Keyed by peerId — stores the per-peer send callback so room events can push to it.
+    const peerSenders = new Map();
+    // Room-level event listeners are registered once per room and fanned out to all
+    // connected peers via peerSenders. We track which rooms have been wired to avoid
+    // double-binding when multiple peers join the same room.
+    const wiredRooms = new Set();
+    function wireRoomEvents(room) {
+        if (wiredRooms.has(room.roomId))
+            return;
+        wiredRooms.add(room.roomId);
+        room.on('speaker_changed', (speakerId) => {
+            broadcast(JSON.stringify({ type: 'speaker_changed', speakerId }));
+        });
+        room.on('concept_mention', (event) => {
+            const { type: _t, ...rest } = event;
+            broadcast(JSON.stringify({ type: 'concept_mention', ...rest }));
+        });
+        room.on('relation_proposed', (event) => {
+            // Broadcast relation proposals to all peers so the product's client-side
+            // instructor UI can queue them for review.
+            const { type: _t, ...rest } = event;
+            broadcast(JSON.stringify({ type: 'relation_proposed', ...rest }));
+        });
+        room.on('attention', (event) => {
+            // Attention events are self-reported by peers — broadcast to all and let
+            // the product filter by role at the application layer.
+            const { type: _t, ...rest } = event;
+            broadcast(JSON.stringify({ type: 'attention', ...rest }));
+        });
+        room.on('track_added', (peerId, trackId, kind) => {
+            broadcast(JSON.stringify({ type: 'track_added', peerId, trackId, kind }));
+        });
+        room.on('track_removed', (peerId, trackId) => {
+            broadcast(JSON.stringify({ type: 'track_removed', peerId, trackId }));
+        });
+        room.on('transcript', (peerId, text, isFinal, sessionMs) => {
+            broadcast(JSON.stringify({ type: 'transcript', peerId, text, isFinal, sessionMs }));
+        });
+    }
+    function broadcast(message) {
+        for (const send of peerSenders.values()) {
+            send(message);
+        }
+    }
+    return {
+        async handleUpgrade(request) {
+            const user = await config.authenticate(request);
+            if (!user)
+                return null;
+            const roomId = config.resolveRoomId(request);
+            const peerId = config.resolvePeerId(request, user);
+            const options = config.roomOptions?.(request, user) ?? {};
+            const existing = await config.server.getRoom(roomId);
+            const room = existing !== null ? existing : await config.server.createRoom(roomId, options);
+            wireRoomEvents(room);
+            return { peerId, room, joined: false };
+        },
+        async handleMessage(session, data, send) {
+            // Register this peer's send callback so room events reach them.
+            peerSenders.set(session.peerId, send);
+            let msg;
+            try {
+                msg = JSON.parse(data);
+            }
+            catch {
+                send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+                return;
+            }
+            const { type } = msg;
+            if (type === 'offer') {
+                const sdpOffer = msg['sdp'];
+                if (typeof sdpOffer !== 'string') {
+                    send(JSON.stringify({ type: 'error', message: 'Missing sdp in offer' }));
+                    return;
+                }
+                try {
+                    const sdpAnswer = await session.room.addPeer(session.peerId, sdpOffer);
+                    session.joined = true;
+                    send(JSON.stringify({ type: 'answer', sdp: sdpAnswer }));
+                }
+                catch (err) {
+                    send(JSON.stringify({ type: 'error', message: String(err) }));
+                }
+                return;
+            }
+            if (type === 'ice') {
+                const candidate = msg['candidate'];
+                if (typeof candidate !== 'string') {
+                    send(JSON.stringify({ type: 'error', message: 'Missing candidate in ice message' }));
+                    return;
+                }
+                try {
+                    await session.room.addIceCandidate(session.peerId, candidate);
+                }
+                catch (err) {
+                    send(JSON.stringify({ type: 'error', message: String(err) }));
+                }
+                return;
+            }
+            if (type === 'data') {
+                const channel = msg['channel'];
+                const rawData = msg['data'];
+                if (typeof channel !== 'string' || !Array.isArray(rawData)) {
+                    send(JSON.stringify({ type: 'error', message: 'Invalid data channel message' }));
+                    return;
+                }
+                session.room.sendData(channel, Buffer.from(rawData));
+                return;
+            }
+            if (type === 'leave') {
+                await session.room.removePeer(session.peerId).catch(() => undefined);
+                peerSenders.delete(session.peerId);
+                session.joined = false;
+                return;
+            }
+            send(JSON.stringify({ type: 'error', message: `Unknown message type: ${String(type)}` }));
+        },
+        async handleClose(session) {
+            peerSenders.delete(session.peerId);
+            if (session.joined) {
+                await session.room.removePeer(session.peerId).catch(() => undefined);
+                session.joined = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=hall-handlers.js.map

package/dist/server/hall-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hall-handlers.js","sourceRoot":"","sources":["../../src/server/hall-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AASH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAiHnC,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAA8B;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,CAAA;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAA;IACrD,MAAM,QAAQ,GAAG,GAAG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAA;IACjD,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC;SAChD,MAAM,CAAC,QAAQ,CAAC;SAChB,MAAM,CAAC,QAAQ,CAAC,CAAA;IACnB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAC1C,CAAC;AAED,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA6B;IACjE,qFAAqF;IACrF,MAAM,WAAW,GAAG,IAAI,GAAG,EAAqC,CAAA;IAEhE,gFAAgF;IAChF,iFAAiF;IACjF,yDAAyD;IACzD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAA;IAEpC,SAAS,cAAc,CAAC,IAAU;QAChC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAM;QACvC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAE3B,IAAI,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,SAAiB,EAAE,EAAE;YAC/C,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;QACnE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,KAAmB,EAAE,EAAE;YACjD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;YACnC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAA;QACjE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAA4B,EAAE,EAAE;YAC5D,yEAAyE;YACzE,2CAA2C;YAC3C,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;YACnC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAA;QACnE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,KAAqB,EAAE,EAAE;YAC7C,yEAAyE;YACzE,uDAAuD;YACvD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;YACnC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAA;QAC3D,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,MAAc,EAAE,OAAe,EAAE,IAAuB,EAAE,EAAE;YAClF,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC3E,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,MAAc,EAAE,OAAe,EAAE,EAAE;YAC3D,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;QACvE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAc,EAAE,IAAY,EAAE,OAAgB,EAAE,SAAiB,EAAE,EAAE;YAC1F,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;QACrF,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,SAAS,SAAS,CAAC,OAAe;QAChC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,CAAA;QACf,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,OAAgB;YAClC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;YAC/C,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAA;YAEtB,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAElD,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAA;YACzD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YACpD,MAAM,IAAI,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YAE3F,cAAc,CAAC,IAAI,CAAC,CAAA;YAEpB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;QACxC,CAAC;QAED,KAAK,CAAC,aAAa,CACjB,OAAoB,EACpB,IAAY,EACZ,IAA+B;YAE/B,gEAAgE;YAChE,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YAErC,IAAI,GAA4B,CAAA;YAChC,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAA;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAA;gBAChE,OAAM;YACR,CAAC;YAED,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,CAAA;YAEpB,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAuB,CAAA;gBACjD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACjC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAA;oBACxE,OAAM;gBACR,CAAC;gBACD,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;oBACtE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAA;oBACrB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;gBAC1D,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;gBAC/D,CAAC;gBACD,OAAM;YACR,CAAC;YAED,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBACnB,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAA;gBACxD,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAClC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kCAAkC,EAAE,CAAC,CAAC,CAAA;oBACpF,OAAM;gBACR,CAAC;gBACD,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;gBAC/D,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;gBAC/D,CAAC;gBACD,OAAM;YACR,CAAC;YAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAuB,CAAA;gBACpD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAA;gBAC3B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3D,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC,CAAA;oBAChF,OAAM;gBACR,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAmB,CAAC,CAAC,CAAA;gBAChE,OAAM;YACR,CAAC;YAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;gBACpE,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;gBAClC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAA;gBACtB,OAAM;YACR,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;QAC3F,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,OAAoB;YACpC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YAClC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnB,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;gBACpE,OAAO,CAAC,MAAM,GAAG,KAAK,CAAA;YACxB,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}