@soulcraft/sdk 1.1.0 → 1.2.0

package/dist/server/index.d.ts

@@ -36,12 +36,14 @@ export { BrainyInstancePool, BrainyInitializingError, computeEmailHash, } from '
 export type { InstancePoolConfig, InstancePoolStats, } from './instance-pool.js';
 export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
 export type { BrainyHandlerConfig, BrainyWsHandlerConfig, BrainyWsHandler, WsSession, } from './handlers.js';
-export { createHallRoomHandler, generateTurnCredentials, } from './hall-handlers.js';
-export type { HallRoomHandlerConfig, HallRoomHandler, HallSession, TurnCredentialOptions, TurnCredentials, } from './hall-handlers.js';
+export { createHallModule, generateTurnCredentials, HallClient, } from './hall-handlers.js';
+export type { HallConnectionOptions, HallModule, TurnCredentialOptions, TurnCredentials, } from './hall-handlers.js';
+export type { HallRoom, HallRoomEvents, RoomOptions, ConceptInput, RecordingManifest, TranscriptEvent, ConceptMentionEvent, RelationProposedEvent, SpeakerChangedEvent, PeerJoinedEvent, PeerLeftEvent, } from '../modules/hall/types.js';
 export { createAuthMiddleware, createRemoteSessionVerifier, AUTH_USER_KEY, } from '../modules/auth/middleware.js';
 export type { AuthMiddlewareOptions, AuthMiddleware, AuthContext, BetterAuthLike, RemoteSessionVerifierOptions, } from '../modules/auth/middleware.js';
 export { createBackchannelLogoutHandler } from '../modules/auth/backchannel.js';
 export type { BackchannelLogoutConfig, BackchannelAuthLike, } from '../modules/auth/backchannel.js';
+export { verifyServiceToken, extractBearerToken, } from '../modules/auth/service-token.js';
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
 export { createSDK } from './create-sdk.js';
 export type { CreateSDKOptions } from './create-sdk.js';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,cAAc,EACd,4BAA4B,GAC7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,YAAY,EACV,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAG7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACxF,YAAY,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,qBAAqB,EACrB,UAAU,EACV,qBAAqB,EACrB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,aAAa,GACd,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,cAAc,EACd,4BAA4B,GAC7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,YAAY,EACV,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAG7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACxF,YAAY,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/server/index.js

@@ -36,11 +36,13 @@
 export { BrainyInstancePool, BrainyInitializingError, computeEmailHash, } from './instance-pool.js';
 // ── Handler factories ─────────────────────────────────────────────────────────
 export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
-// ── Hall handler factories ────────────────────────────────────────────────────
-export { createHallRoomHandler, generateTurnCredentials, } from './hall-handlers.js';
+// ── Hall module factory + TURN utilities ─────────────────────────────────────
+export { createHallModule, generateTurnCredentials, HallClient, } from './hall-handlers.js';
 // ── Auth middleware + backchannel logout ──────────────────────────────────────
 export { createAuthMiddleware, createRemoteSessionVerifier, AUTH_USER_KEY, } from '../modules/auth/middleware.js';
 export { createBackchannelLogoutHandler } from '../modules/auth/backchannel.js';
+// ── Service token verification ────────────────────────────────────────────────
+export { verifyServiceToken, extractBearerToken, } from '../modules/auth/service-token.js';
 // ── Auth config helpers (also on shared entry, duplicated here for convenience) ─
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
 // ── createSDK factory ─────────────────────────────────────────────────────────

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,iFAAiF;AACjF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA;AAS3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AAQtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,mFAAmF;AACnF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,qFAAqF;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,gFAAgF;AAChF,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAqB3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AAQtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAEzC,mFAAmF;AACnF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,qFAAqF;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/types.d.ts

@@ -118,26 +118,30 @@ export interface ServerSDKOptions extends SDKOptions {
     };
     /**
      * Optional Hall real-time communication configuration.
-     * When present, the SDK initializes a HallServer and exposes it as sdk.hall.
-     * Requires @soulcraft/hall to be installed.
+     * When present, the SDK connects to the Hall standalone server and exposes `sdk.hall`.
+     * No additional packages required — Hall support is built into `@soulcraft/sdk`.
      */
     hall?: {
-        /** Public IP address announced in WebRTC ICE candidates. Required in production. */
-        publicIp: string;
-        /** UDP port range start for ICE candidates (default: 40000). */
-        portMin?: number;
-        /** UDP port range end for ICE candidates (default: 49999). */
-        portMax?: number;
-        /** TURN server URL, e.g. "turn:hall.soulcraft.com:3478". */
-        turnUrl?: string;
-        /** TURN credentials username (static; use generateTurnCredentials for per-peer creds). */
-        turnUsername?: string;
-        /** TURN credentials password (static). */
-        turnPassword?: string;
-        /** S3 bucket name for recording uploads. */
-        recordingBucket?: string;
-        /** Deepgram API key for real-time transcription. */
-        deepgramApiKey?: string;
+        /**
+         * Hall server WebSocket URL (e.g. `"wss://hall.soulcraft.com"`).
+         * Defaults to `process.env.HALL_URL` if not set.
+         */
+        url: string;
+        /**
+         * Product name as configured in `[auth.products]` in `hall.toml`.
+         * e.g. `"academy"`, `"workshop"`, `"venue"`.
+         */
+        productName: string;
+        /**
+         * Shared secret for this product. Set via `HALL_<PRODUCT>_SECRET` env var.
+         * Never expose this to browsers.
+         */
+        secret: string;
+        /**
+         * Milliseconds to wait before a reconnect attempt after an unexpected disconnect.
+         * Default: 2000.
+         */
+        reconnectDelayMs?: number;
     };
 }
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/USAGE.md

@@ -24,7 +24,8 @@ the Soulcraft platform. It covers every implemented module with working examples
 10. [BrainyInstancePool — Instance Lifecycle](#brainyinstancepool--instance-lifecycle)
 11. [Capability Tokens — Cross-Product Access](#capability-tokens--cross-product-access)
 12. [Auth Middleware](#auth-middleware)
-13. [For AI Assistants](#for-ai-assistants)
+13. [sdk.hall — Real-Time Communication](#sdkhall--real-time-communication)
+14. [For AI Assistants](#for-ai-assistants)
 
 ---
 
@@ -586,6 +587,223 @@ app.post('/api/auth/backchannel-logout', backchannelHandler)
 
 ---
 
+## sdk.hall — Real-Time Communication
+
+Hall is the Soulcraft real-time communication layer: WebRTC SFU, Whisper ASR transcription,
+BERT concept matching, and session recording. It runs as a standalone Rust binary at
+`hall.soulcraft.com` and is accessed via `sdk.hall.*` on the server and `joinHallRoom()`
+in the browser.
+
+**Architecture overview:**
+
+```
+Product backend ──(shared secret)──► Hall server ◄──(session token)── Browser
+      │                                    │
+  sdk.hall.*                          joinHallRoom()
+  (HallModule)                        (HallRoomHandle)
+```
+
+- The **product secret** (`HALL_WORKSHOP_SECRET` etc.) is server-to-server only — never sent to browsers.
+- The **session token** is a short-lived JWT issued by `sdk.hall.createSessionToken()` — safe to pass to browsers.
+
+### Server setup
+
+```typescript
+import { createSDK, createHallModule } from '@soulcraft/sdk/server'
+
+// Create the Hall module at startup (one per process):
+const hall = createHallModule({
+  url: process.env.HALL_URL ?? 'wss://hall.soulcraft.com',
+  productName: 'workshop',                         // must match hall.toml [auth.products]
+  secret: process.env.HALL_WORKSHOP_SECRET!,       // never sent to browsers
+  reconnectDelayMs: 2000,                          // default
+})
+
+await hall.connect()
+
+// Lifecycle hooks:
+hall.onDisconnect(() => console.warn('Hall: disconnected'))
+hall.onReconnect(() => console.log('Hall: reconnected'))
+```
+
+### Creating and managing rooms
+
+```typescript
+import type { RoomOptions } from '@soulcraft/sdk'
+
+// Create a room (e.g. when a learning session starts):
+const room = await hall.createRoom('session-abc123', {
+  maxPeers: 6,
+  enableTranscription: true,
+  enableRecording: false,
+  entityId: 'entity-uuid',             // Brainy entity to attach AI events to
+  concepts: [                          // BERT concept matching inputs
+    { nodeId: 'node-1', name: 'Maillard reaction', nounType: 'concept' },
+    { nodeId: 'node-2', name: 'fermentation',       nounType: 'concept' },
+  ],
+})
+
+// Listen to room events on the server side:
+room.on('transcriptEvent', (event) => {
+  // event: { sessionId, speakerId, peerId, text, isFinal, timestampMs, confidence }
+  if (event.isFinal) saveTranscriptLine(event.text)
+})
+
+room.on('conceptMentionEvent', (event) => {
+  // event: { sessionId, nodeId, name, confidence, timestampMs, transcriptSnippet }
+  console.log(`Concept mentioned: "${event.name}" (${event.confidence.toFixed(2)})`)
+})
+
+room.on('relationProposedEvent', (event) => {
+  // event: { sessionId, fromNodeId, toNodeId, verb, confidence, evidence }
+  // Automatically proposed by Hall based on transcript — accept or discard:
+  if (event.confidence > 0.75) {
+    await sdk.brainy.relate({ from: event.fromNodeId, to: event.toNodeId, type: event.verb })
+  }
+})
+
+room.on('speakerChangedEvent', (event) => {
+  // event: { sessionId, peerId, speakerId, timestampMs }
+  updateActiveSpeaker(event.peerId)
+})
+
+room.on('peerJoinedEvent', (event) => {
+  // event: { sessionId, peerId, displayName }
+})
+
+room.on('peerLeftEvent', (event) => {
+  // event: { sessionId, peerId }
+  checkIfRoomEmpty(event.sessionId)
+})
+
+// Get or close rooms:
+const existing = await hall.getRoom('session-abc123')  // HallRoom | null
+const all = await hall.listRooms()                     // string[]
+await hall.closeRoom('session-abc123')
+```
+
+### Issuing session tokens for browsers
+
+The product backend issues a short-lived token so the browser can join a room without
+ever seeing the product secret:
+
+```typescript
+app.post('/api/hall/token', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const { roomId } = await c.req.json()
+
+  const token = await hall.createSessionToken({
+    roomId,
+    userId: user.id,
+    displayName: user.name ?? user.email,
+    // ttlMs: 300_000   // default: 5 minutes
+  })
+
+  return c.json({ token })
+})
+```
+
+### Recording
+
+```typescript
+// Start recording (returns when recording is underway):
+await hall.startRecording('session-abc123')
+
+// Stop and get the manifest:
+room.on('recordingManifest', (manifest) => {
+  // manifest: { sessionId, startedAt, endedAt, audioTracks, videoTracks }
+  //   audioTracks: Array<{ peerId, url, durationMs }>
+  //   videoTracks: Array<{ peerId, url, durationMs }>
+  saveRecordingManifest(manifest)
+})
+
+await hall.stopRecording('session-abc123')
+```
+
+### Browser — joinHallRoom
+
+```typescript
+import { joinHallRoom } from '@soulcraft/sdk/client'
+import type { HallRoomHandle } from '@soulcraft/sdk'
+
+// 1. Get a session token from your backend:
+const { token } = await fetch('/api/hall/token', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ roomId: 'session-abc123' }),
+}).then(r => r.json())
+
+// 2. Join the room:
+const room: HallRoomHandle = await joinHallRoom({
+  url: 'wss://hall.soulcraft.com',
+  roomId: 'session-abc123',
+  token,                             // short-lived JWT, not the product secret
+})
+
+// 3. Add local media stream:
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true })
+room.addStream(stream)
+
+// 4. Listen to events — same event names as the server-side HallRoom:
+room.on('trackAdded', ({ peerId, track, stream }) => {
+  // Attach track to a <video> or <audio> element
+  const el = document.getElementById(`peer-${peerId}`) as HTMLVideoElement
+  el.srcObject = stream
+})
+
+room.on('trackRemoved', ({ peerId, track }) => {
+  removeTrackFromUI(peerId, track)
+})
+
+room.on('transcriptEvent', (event) => {
+  appendSubtitle(event.text, event.isFinal)
+})
+
+room.on('conceptMentionEvent', (event) => {
+  highlightConcept(event.nodeId, event.confidence)
+})
+
+room.on('relationProposedEvent', (event) => {
+  showRelationSuggestion(event)
+})
+
+room.on('speakerChangedEvent', (event) => {
+  setActiveSpeakerIndicator(event.peerId)
+})
+
+room.on('peerJoinedEvent', ({ peerId, displayName }) => {
+  addParticipant(peerId, displayName)
+})
+
+room.on('peerLeftEvent', ({ peerId }) => {
+  removeParticipant(peerId)
+})
+
+// 5. Clean up:
+room.close()
+```
+
+### Environment variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `HALL_URL` | Hall server WebSocket URL | Yes (or pass `url` in config) |
+| `HALL_WORKSHOP_SECRET` | Shared secret for Workshop | If product is `workshop` |
+| `HALL_VENUE_SECRET` | Shared secret for Venue | If product is `venue` |
+| `HALL_ACADEMY_SECRET` | Shared secret for Academy | If product is `academy` |
+
+The secret name follows the convention `HALL_<PRODUCT_UPPERCASE>_SECRET`. It is defined
+in `hall.toml` on the Hall server side under `[auth.products]`.
+
+### Security rules
+
+1. **Product secrets are server-side only.** Never pass `HALL_*_SECRET` to browsers or kit code.
+2. **Session tokens are short-lived** (default 5 minutes). Always issue fresh tokens per session.
+3. **`roomId` is opaque** — the browser can only join rooms that the backend creates. Kit code cannot create rooms directly.
+4. Hall validates the token signature on every WebSocket connection, so stolen tokens cannot be replayed after expiry.
+
+---
+
 ## For AI Assistants
 
 When helping implement Soulcraft server code, follow this checklist:
@@ -627,6 +845,7 @@ sdk.events.emit('custom:event', payload)
 | `sdk.events.*` | ✅ Implemented | EventEmitter, typed, local to SDK instance |
 | `sdk.skills.*` | ✅ Implemented | VFS + bundled registry fallback |
 | `sdk.versions.*` | ✅ Types only | Runtime proxy works; Brainy versions API |
+| `sdk.hall.*` | ✅ Implemented | Server: `createHallModule()`. Browser: `joinHallRoom()` |
 | `sdk.license.*` | ❌ Not yet | Will throw if accessed |
 | `sdk.kits.*` | ❌ Not yet | Will throw if accessed |
 | `sdk.formats.*` | ❌ Not yet | Will throw if accessed |
@@ -644,3 +863,7 @@ sdk.events.emit('custom:event', payload)
 | `BETTER_AUTH_SECRET` | better-auth | Yes |
 | `BRAINY_DATA_PATH` | BrainyInstancePool | Yes (defaults to `./brainy-data`) |
 | `STORAGE_TYPE` | BrainyInstancePool | Yes (`filesystem` or `mmap-filesystem`) |
+| `HALL_URL` | `sdk.hall` | Yes if Hall is enabled |
+| `HALL_WORKSHOP_SECRET` | `sdk.hall` (Workshop) | If product is `workshop` |
+| `HALL_VENUE_SECRET` | `sdk.hall` (Venue) | If product is `venue` |
+| `HALL_ACADEMY_SECRET` | `sdk.hall` (Academy) | If product is `academy` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {
@@ -38,15 +38,11 @@
   "peerDependencies": {
     "@soulcraft/brainy": ">=7.17.0",
     "@soulcraft/cortex": ">=2.1.5",
-    "@soulcraft/hall": ">=0.1.0",
     "@soulcraft/kit-schema": ">=2.0.0",
     "@soulcraft/kits": ">=1.0.0",
     "firebase-admin": ">=12.0.0"
   },
   "peerDependenciesMeta": {
-    "@soulcraft/hall": {
-      "optional": true
-    },
     "@soulcraft/kit-schema": {
       "optional": true
     },
@@ -65,7 +61,6 @@
     "stripe": "^20.4.0"
   },
   "devDependencies": {
-    "@soulcraft/hall": "link:@soulcraft/hall",
     "@types/node": "^22.0.0",
     "hono": "^4.12.3",
     "typescript": "^5.7.0",