@soulcraft/sdk 2.0.1 → 2.1.0

package/dist/server/index.js

@@ -3,21 +3,14 @@
  * @description Server entry point for @soulcraft/sdk. Exports everything needed to
  * run the SDK in a product backend (Hono, SvelteKit, or any Bun/Node server).
  *
- * ## SDK 2.0 — Namespace router (recommended)
- *
  * Use `createSoulcraftRouter()` to mount a single Hono router that handles ALL
  * 25 SDK namespaces via a unified `/api/rpc` endpoint. Products configure which
  * namespaces are active via `NamespaceProviders`.
  *
- * ## Legacy — Brainy-only handlers
- *
- * `createBrainyHandler()` and `createBrainyWsHandler()` still work for backward
- * compatibility but only handle the `brainy` namespace.
- *
  * This entry point must never be imported in browser bundles — it has hard
  * server-only dependencies (`@soulcraft/brainy`, `lru-cache`, `crypto`, `fs`).
  *
- * @example SDK 2.0 — unified router
+ * @example Unified router
  * ```typescript
  * import { createSoulcraftRouter, BrainyInstancePool } from '@soulcraft/sdk/server'
  *
@@ -33,44 +26,32 @@
  */
 // ── Instance pool ─────────────────────────────────────────────────────────────
 export { BrainyInstancePool, computeEmailHash, } from './instance-pool.js';
-// ── Handler factories ─────────────────────────────────────────────────────────
-export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
 // ── Y.js document manager (collaborative editing) ─────────────────────────────
 export { YDocManager } from '../modules/brainy/ydoc-manager.js';
-// ── PostMessage handler (Workshop parent-frame ↔ kit iframe) ──────────────────
-export { createBrainyPostMessageHandler } from './postmessage-handler.js';
-// ── Hall module factory + TURN utilities ─────────────────────────────────────
-export { createHallModule, generateTurnCredentials, HallClient, } from './hall-handlers.js';
+// ── Hall module factory + media client + TURN utilities ──────────────────────
+export { createHallModule, createHallMediaClient, generateTurnCredentials, HallClient, HallMediaClient, } from './hall-handlers.js';
 // ── Auth middleware + session factories ───────────────────────────────────────
 export { createAuthMiddleware, createRemoteSessionVerifier, createDevSessionVerifier, createDevLoginHandler, createDevCookieVerifier, createGuestSessionHandler, createGuestCookieVerifier, 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) ─
+// ── Auth config helpers ──────────────────────────────────────────────────────
 export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
 // ── Product registry — single source of truth for all Soulcraft products ─────
 export { SOULCRAFT_PRODUCTS, deriveOrigins, deriveRedirectUrls, } from '../modules/auth/products.js';
-// ── createSDK factory ─────────────────────────────────────────────────────────
-export { createSDK } from './create-sdk.js';
-// ── createServerSDK.fromLicense() — license-driven server SDK ─────────────────
-export { createServerSDK } from './from-license.js';
-// ── Module factories (for advanced use — createSDK assembles these automatically) ─
+// ── Module factories ─────────────────────────────────────────────────────────
 export { createBillingModule } from '../modules/billing/index.js';
 export { createLicenseModule } from '../modules/license/index.js';
 export { createKitsModule } from '../modules/kits/index.js';
 export { createNotificationsModule } from '../modules/notifications/index.js';
 export { createCapabilityToken, verifyCapabilityToken } from '../modules/brainy/auth.js';
 export { LocalTransport } from '../transports/local.js';
-// ── Namespace router (Symmetrical SDK 2.0) ──────────────────────────────────
+// ── Namespace router ─────────────────────────────────────────────────────────
 export { createNamespaceRouter } from './namespace-router.js';
-// ── Hono router factory (Symmetrical SDK 2.0) ──────────────────────────────
+// ── Hono router factory ─────────────────────────────────────────────────────
 export { createSoulcraftRouter } from './hono-router.js';
-// ── Namespace handler factories (Symmetrical SDK 2.0) ───────────────────────
+// ── Namespace handler factories ──────────────────────────────────────────────
 // Each factory creates a NamespaceProvider wired into `providers` on the router.
-export { 
-// Handler factories
-createAnnotationsHandler, createAuthHandler, createChatHandler, createCertificationHandler, createCollectionsHandler, createCommerceHandler, createConfigHandler, createExportHandler, createFormatsHandler, createGraphHandler, createImportHandler, createMediaHandler, createProjectHandler, createPublishHandler, createPulseHandler, createRealtimeHandler, createSearchHandler, createSessionHandler, createSettingsHandler, createWorkspaceHandler, } from './handlers/index.js';
-export { 
-// Chat engine utilities
-analyzeComplexity, calculateComplexityScore, selectTieredRouting, createDefaultModelSelector, estimateCost, formatCost, DEFAULT_MODELS, DEFAULT_MODEL_TIERS, streamMessage, sendMessage, } from './handlers/index.js';
+export { createAnnotationsHandler, createAuthHandler, createChatHandler, createCertificationHandler, createCollectionsHandler, createCommerceHandler, createConfigHandler, createExportHandler, createFormatsHandler, createGraphHandler, createImportHandler, createMediaHandler, createProjectHandler, createPublishHandler, createPulseHandler, createRealtimeHandler, createSearchHandler, createSessionHandler, createSettingsHandler, createWorkspaceHandler, } from './handlers/index.js';
+export { analyzeComplexity, calculateComplexityScore, selectTieredRouting, createDefaultModelSelector, estimateCost, formatCost, DEFAULT_MODELS, DEFAULT_MODEL_TIERS, streamMessage, sendMessage, } from './handlers/index.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,iFAAiF;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AAE/D,iFAAiF;AACjF,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAA;AAMzE,gFAAgF;AAChF,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAqB3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,aAAa,GACd,MAAM,+BAA+B,CAAA;AAYtC,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,gFAAgF;AAChF,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,kBAAkB,GACnB,MAAM,6BAA6B,CAAA;AAMpC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAQnD,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;AAK7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEvD,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAY7D,8EAA8E;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAGxD,+EAA+E;AAC/E,iFAAiF;AACjF,OAAO;AACL,oBAAoB;AACpB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AA2D5B,OAAO;AACL,wBAAwB;AACxB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,WAAW,GACZ,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AAE/D,gFAAgF;AAChF,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,eAAe,GAChB,MAAM,oBAAoB,CAAA;AA4C3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,aAAa,GACd,MAAM,+BAA+B,CAAA;AAYtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAEzC,gFAAgF;AAChF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,gFAAgF;AAChF,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,kBAAkB,GACnB,MAAM,6BAA6B,CAAA;AAMpC,gFAAgF;AAChF,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;AAK7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEvD,gFAAgF;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAY7D,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAGxD,gFAAgF;AAChF,iFAAiF;AACjF,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AA0D5B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,YAAY,EACZ,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,WAAW,GACZ,MAAM,qBAAqB,CAAA"}

package/dist/types.d.ts

@@ -17,8 +17,6 @@ export type { SoulcraftProduct };
 import type { SoulcraftNamespaces } from './namespaces.js';
 /** Brainy instance pooling strategies. */
 export type InstanceStrategy = 'per-user' | 'per-tenant' | 'per-scope';
-/** Transport protocols supported by the client SDK. */
-export type Transport = 'http' | 'ws' | 'postmessage' | 'local' | 'auto';
 /**
  * @description The top-level SDK interface. Extends {@link SoulcraftNamespaces} with
  * lifecycle methods for server and client modes.
@@ -42,8 +40,8 @@ export type Transport = 'http' | 'ws' | 'postmessage' | 'local' | 'auto';
  *
  * @example Client
  * ```typescript
- * import { createSoulcraftProxy, HttpTransport } from '@soulcraft/sdk/client'
- * const sdk: SoulcraftSDK = createSoulcraftProxy(new HttpTransport('/api/rpc'))
+ * import { createSoulcraftProxy, HttpRpcTransport } from '@soulcraft/sdk/client'
+ * const sdk: SoulcraftSDK = createSoulcraftProxy(new HttpRpcTransport('/api'))
  * const graph = await sdk.graph.getData()
  * ```
  */
@@ -117,41 +115,4 @@ export interface ServerSDKOptions extends SDKOptions {
         reconnectDelayMs?: number;
     };
 }
-/**
- * @description Options for client mode — connects to a running SDK server over a transport.
- * Use `@soulcraft/sdk/client` entry point.
- *
- * @example Auto-negotiation (WS primary, HTTP fallback)
- * ```typescript
- * const sdk = createClientSDK({ product: 'venue', mode: 'client', transport: 'auto', baseUrl: '/api' })
- * ```
- */
-export interface ClientSDKOptions extends SDKOptions {
-    mode: 'client';
-    /**
-     * Transport strategy.
-     * - `'auto'` — Try WebSocket (MessagePack), fall back to HTTP (JSON). Recommended.
-     * - `'ws'` — WebSocket only. Fails if WS unavailable.
-     * - `'http'` — HTTP only. Stateless, works in serverless and proxy-restricted environments.
-     * - `'postmessage'` — PostMessage only. For WebContainer iframes in dev mode.
-     */
-    transport: 'auto' | 'ws' | 'http' | 'postmessage';
-    /** Base URL for API requests (e.g. `'https://workshop.soulcraft.com'` or `'/api'`). */
-    baseUrl: string;
-    /** Auth strategy: session cookies (same-origin) or a Bearer capability token. */
-    auth?: 'cookie' | {
-        token: string;
-    };
-    /** Request timeout in ms. Defaults to 30 000. */
-    timeoutMs?: number;
-    /**
-     * WebSocket reconnect options. Only relevant when `transport` is `'auto'` or `'ws'`.
-     * Defaults: initialDelayMs = 1000, maxDelayMs = 30000, maxRetries = Infinity.
-     */
-    reconnect?: {
-        initialDelayMs?: number;
-        maxDelayMs?: number;
-        maxRetries?: number;
-    };
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAClE;;;GAGG;AACH,YAAY,EAAE,gBAAgB,EAAE,CAAA;AAEhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;AAEtE,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,CAAA;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACvD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,iDAAiD;IACjD,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,OAAO,EAAE,gBAAgB,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE;QACN,OAAO,EAAE,YAAY,GAAG,iBAAiB,CAAA;QACzC,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE;YACT,QAAQ,EAAE,gBAAgB,CAAA;YAC1B,4EAA4E;YAC5E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAA;YAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;SACtB,CAAA;KACF,CAAA;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,OAAO,EAAE;QACP,mEAAmE;QACnE,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IACD;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACL;;;WAGG;QACH,GAAG,EAAE,MAAM,CAAA;QACX;;;WAGG;QACH,WAAW,EAAE,MAAM,CAAA;QACnB;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,CAAA;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,IAAI,EAAE,QAAQ,CAAA;IACd;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,aAAa,CAAA;IACjD,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAA;IACf,iFAAiF;IACjF,IAAI,CAAC,EAAE,QAAQ,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACnC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAA;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAClE;;;GAGG;AACH,YAAY,EAAE,gBAAgB,EAAE,CAAA;AAEhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;AAGtE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACvD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,iDAAiD;IACjD,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,OAAO,EAAE,gBAAgB,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE;QACN,OAAO,EAAE,YAAY,GAAG,iBAAiB,CAAA;QACzC,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE;YACT,QAAQ,EAAE,gBAAgB,CAAA;YAC1B,4EAA4E;YAC5E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAA;YAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;SACtB,CAAA;KACF,CAAA;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAA;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,OAAO,EAAE;QACP,mEAAmE;QACnE,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IACD;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACL;;;WAGG;QACH,GAAG,EAAE,MAAM,CAAA;QACX;;;WAGG;QACH,WAAW,EAAE,MAAM,CAAA;QACnB;;;WAGG;QACH,MAAM,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,CAAA;CACF"}

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.1",
+  "version": "2.1.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {