@soulcraft/sdk 2.0.0 → 2.0.2

package/docs/ADR-005-hall-integration.md

@@ -0,0 +1,449 @@
+# ADR-005: Hall Integration — Real-Time Communication Layer
+
+**Status:** Accepted
+**Date:** 2026-03-12
+**SDK version:** 1.7.0
+
+---
+
+## Context
+
+Soulcraft needs a real-time communication layer for live sessions (Academy cohorts,
+Workshop collaboration, Venue events). Hall is a standalone Rust server at
+`hall.soulcraft.com` that provides WebRTC SFU, transcription, pub/sub, media processing,
+and broadcast auto-scaling.
+
+The SDK wraps Hall's wire protocol to give products a typed, ergonomic API for both
+server backends and browser clients — without exposing raw WebSocket/msgpack details.
+
+---
+
+## Architecture
+
+### Server/Client Asymmetry
+
+Hall uses a strict separation between control plane (server) and data plane (browser):
+
+```
+┌──────────────────┐     msgpack/WS      ┌──────────────────┐
+│  Product backend  │ ◄──────────────────► │   Hall server    │
+│  (Hono/SvelteKit) │   control plane      │  (Rust, SFU)     │
+└────────┬─────────┘                       └────────┬─────────┘
+         │                                          │
+         │ POST /api/join                           │ WebRTC / WS
+         │ { token, hallUrl }                       │ data plane
+         │                                          │
+         ▼                                          ▼
+┌──────────────────┐     WebRTC + WS      ┌──────────────────┐
+│  Browser kit app  │ ◄──────────────────► │   Hall SFU       │
+│  (joinHallRoom)   │   audio/video/data   │                  │
+└──────────────────┘                       └──────────────────┘
+```
+
+- **Server** (`@soulcraft/sdk/server`): `createHallModule()` returns a `HallModule` that
+  manages rooms, issues tokens, controls recording, manages pub/sub topics, uploads media,
+  and promotes/demotes peers in broadcast rooms.
+
+- **Browser** (`@soulcraft/sdk/client`): `joinHallRoom()` joins a WebRTC room using a
+  short-lived token. `joinHallPubsub()` connects to topic-based messaging.
+
+Products never pass their shared secret to the browser. All browser credentials are
+short-lived tokens issued by the product backend.
+
+### SDK Files
+
+| File | Role |
+|------|------|
+| `src/modules/hall/types.ts` | All TypeScript interfaces and wire protocol message types |
+| `src/modules/hall/server.ts` | `HallClient` — product WebSocket connection to Hall |
+| `src/modules/hall/browser.ts` | `joinHallRoom()`, `joinHallPubsub()` — browser clients |
+| `src/modules/hall/media.ts` | `HallMediaClient` — HTTP client for media pipeline |
+| `src/modules/hall/protocol.ts` | Generic msgpack encode/decode for Hall wire format |
+| `src/server/hall-handlers.ts` | Re-export factories: `createHallModule`, `createHallMediaClient` |
+
+---
+
+## Wire Protocol
+
+Hall uses **msgpack** over WebSocket with a tag/content encoding:
+
+```typescript
+{ t: 'createRoom', d: { roomId: 'cohort-123', options: { ... } } }
+```
+
+The `t` field is the message type (string), `d` is the typed payload. This matches Rust
+serde's `#[serde(tag = "t", content = "d")]` attribute. All field names are camelCase
+(Rust uses `#[serde(rename_all = "camelCase")]`).
+
+The full message unions are defined as `HallClientMessage` (17 variants) and
+`HallServerMessage` (28 variants) in `types.ts`. These are internal to the SDK — products
+never construct raw protocol messages.
+
+---
+
+## Feature Overview
+
+### 1. WebRTC SFU — Small Group Communication
+
+For groups up to 30 participants with full bidirectional audio/video.
+
+**Server side:**
+```typescript
+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,
+  concepts: await loadConcepts(cohortId),
+})
+
+room.on('transcript', (t) => saveTranscript(t))
+room.on('conceptMention', (c) => brain.relate({ from: c.peerId, to: c.nodeId }))
+
+const { token } = await hall.createSessionToken('cohort-123', userId)
+// Return { token, hallUrl } to the browser
+```
+
+**Browser side:**
+```typescript
+import { joinHallRoom } from '@soulcraft/sdk/client'
+
+const room = await joinHallRoom({ token, hallUrl })
+room.addStream(await navigator.mediaDevices.getUserMedia({ video: true, audio: true }))
+
+room.on('trackAdded', ({ peerId, streams }) => {
+  videoElement.srcObject = streams[0]
+})
+room.on('transcript', ({ peerId, text, isFinal }) => {
+  if (isFinal) appendTranscript(peerId, text)
+})
+```
+
+**AI features** — Hall runs Whisper ASR in-process and feeds transcripts through a BERT
+model for concept matching against workspace knowledge graphs. Events flow from Hall →
+product backend → (optionally) browser:
+
+| Event | Description |
+|-------|-------------|
+| `transcript` | Whisper ASR transcript segment (partial or final) |
+| `conceptMention` | BERT matched a concept node from the workspace graph |
+| `relationProposed` | Inferred subject-verb-object relation for review |
+| `speakerChanged` | Active speaker changed (RFC 6464 audio level detection) |
+
+### 2. Three-Tier Broadcast Auto-Scaling
+
+For large audiences (webinars, lectures, live events). Hall automatically scales across
+three tiers based on audience size:
+
+```
+Tier 1: Participant (WebRTC SFU)     — ≤30 peers, full bidirectional, ~50ms latency
+Tier 2: WHEP Viewer (WebRTC recv)    — sub-second latency, receive-only, ~200 peers
+Tier 3: LL-HLS Viewer (HTTP stream)  — 2–3s latency, unlimited scale
+```
+
+**Server setup:**
+```typescript
+const room = await hall.createRoom('lecture-456', {
+  maxParticipants: 5,        // Only 5 can publish (speakers)
+  allowBroadcast: true,      // Overflow joiners become viewers
+  enableRecording: true,
+  recordingComposite: true,  // Mixed MP4 in addition to per-track MKV
+  recordingWebhookUrl: 'https://academy.soulcraft.com/api/recordings/complete',
+})
+
+// Monitor audience
+room.on('viewerCount', ({ participants, whepViewers, hlsViewers }) => {
+  console.log(`${participants} speakers, ${whepViewers + hlsViewers} watching`)
+})
+
+// Promote a viewer to speaker
+hall.promotePeer('lecture-456', 'student-789')
+
+// Demote back to viewer
+hall.demotePeer('lecture-456', 'student-789')
+```
+
+**Browser — role awareness:**
+```typescript
+const room = await joinHallRoom({ token, hallUrl })
+
+room.on('roleChanged', ({ role, canPublish }) => {
+  if (canPublish) {
+    // Promoted — start publishing media
+    room.addStream(await navigator.mediaDevices.getUserMedia({ audio: true }))
+  } else {
+    // Demoted — SDK handles transport downgrade automatically
+    hidePublishUI()
+  }
+})
+
+// Viewers can also connect via WHEP or LL-HLS directly:
+import { getWhepUrl, getHlsUrl } from '@soulcraft/sdk/client'
+
+const whepUrl = getWhepUrl('https://hall.soulcraft.com', 'lecture-456')
+const hlsUrl = getHlsUrl('https://hall.soulcraft.com', 'lecture-456')
+```
+
+**Screen share simulcast:**
+```typescript
+// Server controls the encoding strategy per-peer
+hall.setScreenShareMode('lecture-456', speakerPeerId, 'static')  // Presentations
+hall.setScreenShareMode('lecture-456', speakerPeerId, 'motion')  // Live demos
+```
+
+### 3. Pub/Sub — Topic-Based Messaging with Presence
+
+Product-scoped topic routing with presence tracking, replay buffers, and both server-side
+and browser-side APIs.
+
+**Server side (product backend):**
+```typescript
+// Subscribe and broadcast from the backend
+hall.subscribeTopic('notifications', { service: 'academy' })
+hall.broadcastTopic('notifications', { type: 'cohort-started', cohortId: '123' })
+
+// Listen for pub/sub events
+hall.onPubsub('topicMessage', ({ topic, senderId, payload }) => {
+  console.log(`[${topic}] ${senderId}: ${JSON.stringify(payload)}`)
+})
+hall.onPubsub('presenceUpdate', ({ topic, peerId, action }) => {
+  console.log(`${peerId} ${action} ${topic}`)
+})
+
+// Issue a browser pub/sub token
+const { token } = await hall.createPubsubToken(userId, ['chat:*', 'presence:*'])
+```
+
+**Browser side:**
+```typescript
+import { joinHallPubsub } from '@soulcraft/sdk/client'
+
+const pubsub = await joinHallPubsub({ token, hallUrl: 'wss://hall.soulcraft.com' })
+
+pubsub.subscribe('chat:cohort-123', { username: 'Alice' })
+pubsub.on('topicSubscribed', ({ topic, replay }) => {
+  // replay contains recent messages from the buffer
+  replay.forEach(({ senderId, payload }) => showMessage(senderId, payload))
+})
+pubsub.on('topicMessage', ({ senderId, payload }) => showMessage(senderId, payload))
+pubsub.on('presenceUpdate', ({ peerId, action }) => updatePresence(peerId, action))
+
+pubsub.broadcast('chat:cohort-123', { text: 'Hello everyone!' })
+
+// Cleanup
+pubsub.close()
+```
+
+**Key pub/sub design decisions:**
+- Topics are product-scoped — `academy` cannot see `workshop` topics
+- Replay buffers are per-topic, configurable in `hall.toml`
+- Presence metadata is arbitrary JSON, set at subscribe time
+- Chat in rooms is bridged to pub/sub topic `room:{roomId}:chat`
+
+### 4. Media Pipeline — Upload, Transcode, Retrieve
+
+HTTP-based media processing for audio, video, and images. Async notifications arrive
+over the product WebSocket.
+
+```typescript
+import { createHallMediaClient } from '@soulcraft/sdk/server'
+
+const media = createHallMediaClient({
+  baseUrl: 'https://hall.soulcraft.com',
+  productName: 'workshop',
+  secret: process.env.HALL_WORKSHOP_SECRET!,
+})
+
+// Upload with transcoding
+const { mediaId } = await media.upload(file, { transcode: 'video/mp4' })
+
+// Listen for completion (on any room — media events are product-scoped)
+room.on('mediaReady', ({ mediaId, duration, dimensions }) => {
+  const streamUrl = media.getStreamUrl(mediaId)
+  const thumbUrl = media.getThumbnailUrl(mediaId)
+})
+room.on('mediaError', ({ mediaId, error }) => {
+  console.error(`Media ${mediaId} failed: ${error}`)
+})
+
+// Query media info
+const info = await media.getInfo(mediaId)
+
+// Delete media
+await media.delete(mediaId)
+```
+
+**Auth model for media:**
+- Upload/delete/info use `Authorization: Hall <productName>:<secret>` (server-only)
+- Stream/thumbnail are public `GET /media/{mediaId}/*` endpoints (no auth, browser-safe)
+- WHEP/HLS endpoints are public (browser embeds the URL directly)
+
+### 5. Recording
+
+Per-track MKV recording with optional composite MP4. Recording can be started/stopped
+programmatically or enabled at room creation.
+
+```typescript
+// Start recording on demand
+await hall.startRecording('cohort-123')
+
+// ... later ...
+await hall.stopRecording('cohort-123')
+
+// The room emits a manifest with file paths
+room.on('recordingManifest', (manifest) => {
+  console.log(`Tracks: ${manifest.audioTracks.length} audio, ${manifest.videoTracks.length} video`)
+  if (manifest.compositePath) console.log(`Composite: ${manifest.compositePath}`)
+  if (manifest.cloudUrls) console.log(`Cloud: ${manifest.cloudUrls.join(', ')}`)
+  // Upload to your own storage or use Hall's cloud upload (configured in hall.toml)
+})
+
+// Or configure recording at room creation
+await hall.createRoom('lecture-456', {
+  enableRecording: true,
+  recordingComposite: true,
+  recordingWebhookUrl: 'https://academy.soulcraft.com/api/recordings/complete',
+})
+```
+
+**Webhook:** When configured, Hall POSTs `{ sessionId, manifest }` JSON to the webhook URL
+on recording completion, with exponential backoff retry (3 attempts).
+
+---
+
+## Integration Patterns by Product
+
+### Academy — Cohort Sessions
+
+Academy uses Hall for live cohort sessions with AI-powered concept tracking:
+
+```typescript
+// Server: hooks.server.ts
+const hall = createHallModule({ url, productName: 'academy', secret })
+await hall.connect()
+
+// API route: /api/cohort/:id/join
+const room = await hall.createRoom(cohortId, {
+  enableTranscription: true,
+  concepts: await brain.find({ nounType: 'concept' }),
+  allowBroadcast: true,
+  maxParticipants: 10,
+})
+room.on('conceptMention', async (c) => {
+  await brain.relate({ from: c.peerId, verb: c.verbType, to: c.nodeId })
+})
+room.on('transcript', (t) => saveToLessonLog(cohortId, t))
+const { token } = await hall.createSessionToken(cohortId, userId)
+return { token, hallUrl: process.env.HALL_URL }
+```
+
+### Workshop — Collaborative Editing Sessions
+
+Workshop uses Hall for real-time collaboration alongside Y.js document editing:
+
+```typescript
+const room = await hall.createRoom(`workspace-${workspaceId}`, {
+  enableTranscription: false, // Text-only collaboration
+})
+// Use pub/sub for cursor positions, selection state, awareness
+hall.subscribeTopic(`cursor:${workspaceId}`)
+hall.onPubsub('topicMessage', ({ topic, payload }) => broadcastToYDoc(payload))
+```
+
+### Venue — Live Events and Broadcasts
+
+Venue uses Hall for large-audience events with the full broadcast tier:
+
+```typescript
+const room = await hall.createRoom(`event-${eventId}`, {
+  maxParticipants: 3,    // Panel of speakers
+  allowBroadcast: true,  // Unlimited audience
+  enableRecording: true,
+  recordingComposite: true,
+})
+
+// Browser viewers use WHEP or LL-HLS
+const whepUrl = getWhepUrl(hallUrl, `event-${eventId}`)
+const hlsUrl = getHlsUrl(hallUrl, `event-${eventId}`)
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HALL_URL` | WebSocket URL of the Hall server (`wss://hall.soulcraft.com`) |
+| `HALL_<PRODUCT>_SECRET` | Product-specific shared secret (e.g. `HALL_ACADEMY_SECRET`) |
+
+Secrets are configured in `hall.toml` on the Hall server under `[auth.products.<name>]`.
+
+---
+
+## Exports
+
+### From `@soulcraft/sdk/server`
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `createHallModule` | Function | Create a server-side `HallModule` connection |
+| `createHallMediaClient` | Function | Create an HTTP media pipeline client |
+| `generateTurnCredentials` | Function | Generate ephemeral TURN credentials |
+| `HallClient` | Class | Low-level WebSocket client (advanced use) |
+| `HallMediaClient` | Class | Low-level HTTP media client (advanced use) |
+| `HallModule` | Interface | Full server-side Hall API |
+| `HallRoom` | Interface | Active room handle with event listeners |
+| `HallRoomEvents` | Interface | Event map for room listeners |
+| `HallPubsubEvents` | Interface | Event map for pub/sub listeners |
+
+### From `@soulcraft/sdk/client`
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `joinHallRoom` | Function | Join a WebRTC room from the browser |
+| `joinHallPubsub` | Function | Connect to pub/sub from the browser |
+| `getWhepUrl` | Function | Get WHEP viewer URL for a broadcast room |
+| `getHlsUrl` | Function | Get LL-HLS viewer URL for a broadcast room |
+| `HallRoomHandle` | Interface | Browser room handle with events |
+| `HallRoomHandleEvents` | Interface | Event map for browser room |
+| `HallPubsubHandle` | Interface | Browser pub/sub handle with events |
+| `HallPubsubHandleEvents` | Interface | Event map for browser pub/sub |
+
+### From `@soulcraft/sdk` (shared types)
+
+All Hall types are re-exported from the shared entry for use in any environment.
+`ChatMessage` and `MediaInfo` are exported as `HallChatMessage` and `HallMediaInfo`
+to avoid collisions with the SDK 2.0 namespace types.
+
+---
+
+## Rejected Alternatives
+
+### 1. Embedding WebRTC in the SDK server
+
+**Rejected:** Products could run their own SFU inside the SDK. This would couple the SDK
+to WebRTC dependencies (libwebrtc, TURN), increase binary size, and duplicate what Hall
+already does as a dedicated Rust server. The SDK is a control-plane wrapper, not a
+media server.
+
+### 2. REST API for Hall control
+
+**Rejected:** REST would add HTTP overhead and lose the event-push capability (transcripts,
+concept mentions, media notifications). The persistent WebSocket connection gives
+sub-millisecond event delivery and supports reconnect with state preservation.
+
+### 3. Unified browser transport (WebRTC + pub/sub on same connection)
+
+**Rejected:** WebRTC peer connections and pub/sub topics have different lifecycles, auth
+scopes, and reconnect semantics. Separate connections (`joinHallRoom` vs `joinHallPubsub`)
+keep each concern simple and independently testable.
+
+### 4. GraphQL for media pipeline
+
+**Rejected:** The media pipeline is simple CRUD + upload. REST with `Authorization` header
+is the right fit. GraphQL subscriptions for transcode notifications would duplicate the
+WebSocket event system that already exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {

package/dist/client/create-client-sdk.d.ts

@@ -1,113 +0,0 @@
-/**
- * @module client/create-client-sdk
- * @description `createClientSDK` factory for browser/client-mode @soulcraft/sdk.
- *
- * Assembles a `SoulcraftSDK` from a `ClientSDKOptions` specification. Selects and
- * wires the appropriate transport (`http`, `ws`, or `sse`) and returns a full SDK
- * object whose `sdk.brainy.*` API works identically to server mode.
- *
- * ## Transport selection
- *
- * | `transport` | Use case |
- * |-------------|----------|
- * | `'http'`    | Stateless RPC — kit apps, simple clients. No push events. |
- * | `'ws'`      | Bidirectional RPC + real-time change push. Call `sdk.connect()` first. |
- * | `'sse'`     | Receive-only push events. Pair with `'http'` for outbound RPC. |
- *
- * ## Auth
- *
- * - `auth: 'cookie'` — sends session cookies (same-origin browser use). HTTP only.
- * - `auth: { token }` — sends `Authorization: Bearer <token>`. HTTP and WS.
- * - Omit `auth` for unauthenticated requests (public endpoints).
- *
- * @example HTTP transport (kit app, cookie auth)
- * ```typescript
- * import { createClientSDK } from '@soulcraft/sdk/client'
- *
- * const sdk = createClientSDK({
- *   mode: 'client',
- *   product: 'workshop',
- *   transport: 'http',
- *   baseUrl: 'https://workshop.soulcraft.com',
- *   auth: 'cookie',
- * })
- *
- * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
- * ```
- *
- * @example WebSocket transport (real-time change push)
- * ```typescript
- * import { createClientSDK } from '@soulcraft/sdk/client'
- *
- * const sdk = createClientSDK({
- *   mode: 'client',
- *   product: 'venue',
- *   transport: 'ws',
- *   baseUrl: 'wss://venue.soulcraft.com/api/brainy/ws',
- *   auth: { token: capabilityToken },
- * })
- *
- * await sdk.connect!()
- * sdk.brainy.onDataChange((event) => refreshUI(event))
- * const items = await sdk.brainy.find({ query: 'inventory' })
- * ```
- *
- * @example SSE transport (receive-only change events + HTTP for outbound)
- * ```typescript
- * import { createClientSDK } from '@soulcraft/sdk/client'
- *
- * const sdk = createClientSDK({
- *   mode: 'client',
- *   product: 'venue',
- *   transport: 'sse',
- *   baseUrl: 'https://venue.soulcraft.com',
- *   auth: 'cookie',
- * })
- *
- * // sdk.brainy.onDataChange() fires on live server changes.
- * // sdk.brainy.find() etc. are not available on SSE — wire an HttpTransport separately.
- * sdk.brainy.onDataChange((event) => console.log('change:', event))
- * ```
- */
-import type { SoulcraftSDK } from '../types.js';
-/**
- * Legacy client SDK options. Kept for backward compatibility with `createClientSDK()`.
- * New code should use `createSoulcraftProxy()` with a namespace-aware transport instead.
- */
-interface LegacyClientSDKOptions {
-    mode: 'client';
-    product: string;
-    transport: 'http' | 'ws' | 'sse';
-    baseUrl: string;
-    auth?: 'cookie' | {
-        token: string;
-    };
-    timeoutMs?: number;
-}
-/**
- * Create a client-mode `SoulcraftSDK` from the given options.
- *
- * Selects the transport specified by `options.transport`, wires auth, and returns
- * a `SoulcraftSDK` whose `sdk.brainy.*` surface is identical to server mode.
- *
- * For `'ws'` transport, call `await sdk.connect!()` before making any `sdk.brainy.*`
- * calls to establish the WebSocket connection.
- *
- * @param options - Client SDK options including transport, baseUrl, and auth.
- * @returns A `SoulcraftSDK` backed by the chosen transport.
- *
- * @example HTTP transport
- * ```typescript
- * const sdk = createClientSDK({
- *   mode: 'client',
- *   product: 'workshop',
- *   transport: 'http',
- *   baseUrl: 'https://workshop.soulcraft.com',
- *   auth: 'cookie',
- * })
- * const results = await sdk.brainy.find({ query: 'candle inventory' })
- * ```
- */
-export declare function createClientSDK(options: LegacyClientSDKOptions): SoulcraftSDK;
-export {};
-//# sourceMappingURL=create-client-sdk.d.ts.map

package/dist/client/create-client-sdk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-client-sdk.d.ts","sourceRoot":"","sources":["../../src/client/create-client-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG/C;;;GAGG;AACH,UAAU,sBAAsB;IAC9B,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAAA;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,QAAQ,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY,CAwE7E"}