@soulcraft/sdk 2.0.1 → 2.1.0

package/dist/server/handlers.js

@@ -1,376 +0,0 @@
-/**
- * @module server/handlers
- * @description HTTP RPC and WebSocket handler factories for mounting Brainy server endpoints.
- *
- * Products mount exactly two routes:
- * - `POST /api/brainy/rpc` — handled by {@link createBrainyHandler}
- * - `GET /api/brainy/ws` — WebSocket upgrade handled by {@link createBrainyWsHandler}
- *
- * Both factories are framework-agnostic — they accept and return `Request` / `Response`
- * objects (Fetch API), making them compatible with SvelteKit, Hono, and raw Bun.serve.
- *
- * ## HTTP RPC handler
- *
- * Accepts `{ method: string, args: unknown[] }` as a JSON body and returns
- * `{ result: unknown }` or `{ error: { code, message } }`. All authentication and
- * authorization is delegated to the caller-supplied callbacks.
- *
- * ## WebSocket handler
- *
- * Accepts binary MessagePack frames. See wire protocol in `transports/ws.ts`.
- * The `broadcastChange()` method on the returned handler pushes `BrainyChangeEvent`
- * objects to connected clients.
- *
- * @example SvelteKit route mounting the HTTP handler
- * ```typescript
- * // src/routes/api/brainy/rpc/+server.ts
- * import { createBrainyHandler } from '@soulcraft/sdk/server'
- * import { pool } from '$lib/server/sdk'
- * import { verifySession } from '$lib/server/auth'
- *
- * const handler = createBrainyHandler({
- *   resolveBrain: async (req) => {
- *     const userId = req.headers.get('x-user-id') ?? ''
- *     const workspaceId = req.headers.get('x-workspace-id') ?? ''
- *     return pool.forUser(userId, workspaceId)
- *   },
- *   authenticate: async (req) => verifySession(req.headers.get('cookie') ?? ''),
- * })
- *
- * export const POST: RequestHandler = ({ request }) => handler(request)
- * ```
- *
- * @example Bun.serve WebSocket upgrade
- * ```typescript
- * import { createBrainyWsHandler } from '@soulcraft/sdk/server'
- * import { pool } from './sdk'
- * import { verifyCapabilityToken } from '@soulcraft/sdk'
- *
- * const wsHandler = createBrainyWsHandler({
- *   resolveBrain: (scope) => pool.forTenant(scope),
- *   authenticate: (token, scope) => verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!),
- * })
- *
- * Bun.serve({
- *   async fetch(req, server) {
- *     if (req.url.endsWith('/api/brainy/ws')) {
- *       const session = await wsHandler.handleUpgrade(req)
- *       if (!session) return new Response('Unauthorized', { status: 401 })
- *       server.upgrade(req, { data: session })
- *       return undefined
- *     }
- *     return new Response('Not found', { status: 404 })
- *   },
- *   websocket: {
- *     async message(ws, data) {
- *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
- *     },
- *   },
- * })
- * ```
- */
-import { encode, decode } from '@msgpack/msgpack';
-import { LocalTransport } from '../transports/local.js';
-import { YDocManager } from '../modules/brainy/ydoc-manager.js';
-/**
- * Creates a Fetch-API-compatible HTTP handler for Brainy RPC calls.
- *
- * Mount at `POST /api/brainy/rpc` in your product's router.
- *
- * @param config - Handler configuration.
- * @returns `(request: Request) => Promise<Response>`
- */
-export function createBrainyHandler(config) {
-    const { resolveBrain, authenticate, authorize, blockedMethods = [] } = config;
-    return async function brainyRpcHandler(request) {
-        // ── Auth ──────────────────────────────────────────────────────────────
-        const auth = await authenticate(request);
-        if (!auth)
-            return _jsonError(401, 'UNAUTHORIZED', 'Authentication required');
-        // ── Parse ─────────────────────────────────────────────────────────────
-        let body;
-        try {
-            body = (await request.json());
-        }
-        catch {
-            return _jsonError(400, 'BAD_REQUEST', 'Request body must be valid JSON');
-        }
-        if (typeof body.method !== 'string' || !Array.isArray(body.args)) {
-            return _jsonError(400, 'BAD_REQUEST', '{ method: string, args: unknown[] } required');
-        }
-        const method = body.method;
-        const args = body.args;
-        // ── Blocklist ─────────────────────────────────────────────────────────
-        if (blockedMethods.includes(method)) {
-            return _jsonError(403, 'FORBIDDEN', `Method '${method}' is not available via RPC`);
-        }
-        // ── Authorize ─────────────────────────────────────────────────────────
-        if (authorize) {
-            const allowed = await authorize(method, args, auth);
-            if (!allowed) {
-                return _jsonError(403, 'FORBIDDEN', `Not authorized to call '${method}'`);
-            }
-        }
-        // ── Resolve brain + dispatch ──────────────────────────────────────────
-        let brain;
-        try {
-            brain = await resolveBrain(request);
-        }
-        catch (err) {
-            console.error('[SDK/handler] resolveBrain threw:', err);
-            return _jsonError(503, 'BRAIN_UNAVAILABLE', 'Brainy instance not available');
-        }
-        const transport = new LocalTransport(brain);
-        try {
-            const result = await transport.call(method, args);
-            return new Response(JSON.stringify({ result }), {
-                status: 200,
-                headers: { 'Content-Type': 'application/json' },
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return _jsonError(500, 'RPC_ERROR', message);
-        }
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Factory
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Creates a server-side WebSocket handler for bidirectional Brainy RPC, real-time
- * change push, and optional Y.js collaborative document editing.
- *
- * ## Y.js collaborative editing
- *
- * Pass a `ydocManager` in the config to enable co-editing. The handler will
- * automatically route `y-sync`, `y-update`, and `y-awareness` messages through the
- * manager. The product server must:
- *
- * 1. Maintain a `Map<scope, Map<peerId, sendFn>>` of connected peers.
- * 2. Set `session.broadcast` after `handleUpgrade()` to fan out Y.js frames.
- * 3. Call `handleClose(session)` when a peer disconnects.
- *
- * @example Workshop server wiring with Y.js
- * ```typescript
- * import { createBrainyWsHandler, YDocManager } from '@soulcraft/sdk/server'
- *
- * const ydocManager = new YDocManager()
- * const wsHandler = createBrainyWsHandler({ resolveBrain, authenticate, ydocManager })
- *
- * // Map<scope, Map<peerId, send>>
- * const peers = new Map<string, Map<string, (msg: Uint8Array) => void>>()
- *
- * Bun.serve({
- *   async fetch(req, server) {
- *     if (new URL(req.url).pathname === '/api/brainy/ws') {
- *       const session = await wsHandler.handleUpgrade(req)
- *       if (!session) return new Response('Unauthorized', { status: 401 })
- *       // Register peer in broadcast map
- *       if (!peers.has(session.scope)) peers.set(session.scope, new Map())
- *       server.upgrade(req, { data: session })
- *       return undefined
- *     }
- *   },
- *   websocket: {
- *     open(ws) {
- *       const session = ws.data as WsSession
- *       peers.get(session.scope)!.set(session.peerId, (msg) => ws.send(msg))
- *       session.broadcast = (msg, excludeId) => {
- *         for (const [id, send] of peers.get(session.scope) ?? []) {
- *           if (id !== excludeId) send(msg)
- *         }
- *       }
- *       ws.send(encode({ type: 'ready', scope: session.scope }))
- *     },
- *     async message(ws, data) {
- *       await wsHandler.handleMessage(ws.data, data as ArrayBuffer, (msg) => ws.send(msg))
- *     },
- *     async close(ws) {
- *       const session = ws.data as WsSession
- *       peers.get(session.scope)?.delete(session.peerId)
- *       await wsHandler.handleClose(session)
- *     },
- *   },
- * })
- * ```
- *
- * @param config - Handler configuration.
- * @returns A {@link BrainyWsHandler} instance.
- */
-export function createBrainyWsHandler(config) {
-    const { resolveBrain, authenticate, authorize, blockedMethods = [], ydocManager } = config;
-    return {
-        async handleUpgrade(request) {
-            const url = new URL(request.url);
-            const scope = url.searchParams.get('scope') ?? '';
-            // Browser sends token as ?token= query param; Bun/Node uses Authorization header.
-            const authHeader = request.headers.get('authorization') ?? '';
-            const token = authHeader.startsWith('Bearer ')
-                ? authHeader.slice(7)
-                : (url.searchParams.get('token') ?? '');
-            const auth = await authenticate(token, scope);
-            if (!auth)
-                return null;
-            const brain = await resolveBrain(scope);
-            const transport = new LocalTransport(brain);
-            const peerId = _generatePeerId();
-            // broadcast is a no-op until the product server's websocket.open() sets it.
-            const session = {
-                scope,
-                auth,
-                brain,
-                transport,
-                peerId,
-                broadcast: () => { },
-            };
-            return session;
-        },
-        async handleMessage(session, data, send) {
-            let decoded;
-            try {
-                decoded = decode(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
-            }
-            catch {
-                return; // Malformed frame — silently ignore
-            }
-            if (!decoded || typeof decoded !== 'object')
-                return;
-            const msg = decoded;
-            // ── Y.js messages ────────────────────────────────────────────────────
-            if (typeof msg['type'] === 'string' && msg['type'].startsWith('y-')) {
-                await _handleYjsMessage(msg, session, send, ydocManager);
-                return;
-            }
-            // ── Brainy RPC ───────────────────────────────────────────────────────
-            const req = msg;
-            if (typeof req.id !== 'string' || typeof req.method !== 'string' || !Array.isArray(req.args)) {
-                return;
-            }
-            const { id, method, args } = req;
-            if (blockedMethods.includes(method)) {
-                send(encode({ id, error: { code: 'FORBIDDEN', message: `Method '${method}' blocked` } }));
-                return;
-            }
-            if (authorize) {
-                const allowed = await authorize(method, args, session.auth);
-                if (!allowed) {
-                    send(encode({ id, error: { code: 'FORBIDDEN', message: `Not authorized: '${method}'` } }));
-                    return;
-                }
-            }
-            try {
-                const result = await session.transport.call(method, args);
-                send(encode({ id, result }));
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                send(encode({ id, error: { code: 'RPC_ERROR', message } }));
-            }
-        },
-        async handleClose(session) {
-            if (!ydocManager)
-                return;
-            // Notify YDocManager for every file this peer had open.
-            // The manager tracks peers per-file; onPeerDisconnect flushes + discards
-            // when the last peer leaves a document.
-            //
-            // We don't track which files each peer opened at the session level —
-            // YDocManager.onPeerDisconnect is idempotent for peers that never joined a doc.
-            // The product server can also call this selectively if it tracks open files.
-            //
-            // For simplicity, the manager handles the "peer not known for this file" case
-            // gracefully (no-op).
-            await ydocManager.onPeerDisconnectAll(session.scope, session.peerId);
-        },
-        broadcastChange(event, send) {
-            send(encode(event));
-        },
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Internal helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Builds a JSON error response with `{ error: { code, message } }` body.
- *
- * @param status - HTTP status code.
- * @param code - Machine-readable error code.
- * @param message - Human-readable description.
- * @returns A `Response` with the error payload.
- */
-function _jsonError(status, code, message) {
-    return new Response(JSON.stringify({ error: { code, message } }), {
-        status,
-        headers: { 'Content-Type': 'application/json' },
-    });
-}
-/**
- * Routes a Y.js protocol message to the appropriate `YDocManager` method and
- * broadcasts updates to other peers via `session.broadcast`.
- *
- * ## Sync protocol (Y.js standard two-phase handshake):
- * 1. Client connects → sends `y-sync` with its state vector.
- * 2. Server replies with `y-sync` diff (all updates client is missing).
- * 3. Client applies diff → sends `y-update` for each pending local op.
- * 4. From this point: all ops are `y-update` frames, broadcast to all other peers.
- *
- * ## Awareness:
- * - `y-awareness` frames carry cursor positions, user name/color, selection ranges.
- * - NOT persisted — forwarded immediately to all other peers then discarded.
- *
- * @param msg - Decoded Y.js message frame.
- * @param session - The WebSocket session for the sending peer.
- * @param send - Sends a response to THIS peer only.
- * @param ydocManager - The server-side Y.Doc pool (may be undefined if collab disabled).
- */
-async function _handleYjsMessage(msg, session, send, ydocManager) {
-    if (!ydocManager)
-        return;
-    switch (msg.type) {
-        case 'y-sync': {
-            // Phase 1 of the Y.js sync handshake.
-            // Client sends its state vector; server replies with the diff.
-            const clientSv = msg.stateVector instanceof Uint8Array
-                ? msg.stateVector
-                : new Uint8Array(Object.values(msg.stateVector));
-            const diff = await ydocManager.getDiff(session.scope, msg.filePath, session.brain, clientSv);
-            // Reply only to this peer with the diff so it can catch up.
-            send(encode({ type: 'y-sync', filePath: msg.filePath, diff }));
-            break;
-        }
-        case 'y-update': {
-            // A CRDT update from this peer — apply it and fan out to all others.
-            const update = msg.update instanceof Uint8Array
-                ? msg.update
-                : new Uint8Array(Object.values(msg.update));
-            // Ensure this peer is registered as active for this document.
-            await ydocManager.getOrCreate(session.scope, msg.filePath, session.brain, session.peerId);
-            await ydocManager.applyUpdate(session.scope, msg.filePath, update);
-            // Broadcast to all OTHER peers in this scope.
-            const frame = encode({ type: 'y-update', filePath: msg.filePath, update });
-            session.broadcast(frame, session.peerId);
-            break;
-        }
-        case 'y-awareness': {
-            // Cursor / presence update — forward to all other peers, do not persist.
-            const update = msg.update instanceof Uint8Array
-                ? msg.update
-                : new Uint8Array(Object.values(msg.update));
-            const frame = encode({ type: 'y-awareness', update });
-            session.broadcast(frame, session.peerId);
-            break;
-        }
-    }
-}
-/**
- * Generates a unique peer ID for a new WebSocket connection.
- *
- * Uses `crypto.randomUUID()` which is available in Bun, Node 19+, and modern browsers.
- *
- * @returns A UUID string.
- */
-function _generatePeerId() {
-    return crypto.randomUUID();
-}
-//# sourceMappingURL=handlers.js.map

package/dist/server/handlers.js.map

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

package/dist/server/postmessage-handler.d.ts

@@ -1,152 +0,0 @@
-/**
- * @module server/postmessage-handler
- * @description Parent-frame PostMessage handler for Workshop WebContainer kit iframes.
- *
- * Workshop kit apps run as WebContainer iframes inside the Workshop editor. They use
- * {@link PostMessageTransport} from `@soulcraft/sdk/client` to post Brainy RPC calls to the
- * parent Workshop frame. This module provides the parent-side handler that receives those
- * calls, dispatches them to the live Brainy instance, and posts the response back.
- *
- * ## Wire protocol
- *
- * **Inbound** (from kit iframe):
- * ```json
- * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{...}] }
- * ```
- *
- * **Outbound** (to kit iframe):
- * ```json
- * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
- * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "...", "message": "..." } }
- * ```
- *
- * ## Usage (Workshop parent frame)
- *
- * ```typescript
- * import { createBrainyPostMessageHandler } from '@soulcraft/sdk/server'
- * import { createSDK, BrainyInstancePool } from '@soulcraft/sdk/server'
- *
- * const pool = new BrainyInstancePool({ ... })
- *
- * // Mount once per kit iframe window:
- * const handler = createBrainyPostMessageHandler({
- *   resolveBrain: async (method) => {
- *     const brain = await pool.forUser(currentUser.emailHash, currentWorkspaceId)
- *     return brain
- *   },
- *   allowedOrigin: 'null',   // WebContainer iframes have origin 'null'
- *   targetWindow: kitIframeRef.contentWindow!,
- * })
- *
- * // When the kit iframe is torn down:
- * handler.dispose()
- * ```
- *
- * ## Security
- *
- * The handler validates the `event.origin` against `allowedOrigin` before dispatching.
- * WebContainer iframes have `origin: 'null'` — pass `'null'` (string) for those.
- * For externally hosted kit apps, pass the expected origin string.
- *
- * Optionally, set `allowedSource` to the `contentWindow` of the specific iframe to
- * reject messages from other frames on the same origin.
- */
-import type { Brainy } from '@soulcraft/brainy';
-import type { BrainyChangeEvent } from '../modules/brainy/events.js';
-/**
- * Configuration for {@link createBrainyPostMessageHandler}.
- */
-export interface BrainyPostMessageHandlerConfig {
-    /**
-     * Resolve the Brainy instance to use for a given RPC call.
-     *
-     * Called once per request. Workshop typically resolves from a `BrainyInstancePool`
-     * keyed to the current user and workspace.
-     *
-     * @param method - The Brainy method being called (e.g. `'find'`, `'vfs.readFile'`).
-     * @returns A live Brainy instance.
-     */
-    resolveBrain: (method: string) => Promise<Brainy> | Brainy;
-    /**
-     * The expected `event.origin` of inbound messages.
-     *
-     * Messages from any other origin are silently ignored.
-     * Pass `'null'` (string) for WebContainer iframes, which always report origin `'null'`.
-     * Pass `'*'` to accept any origin (not recommended in production).
-     */
-    allowedOrigin: string;
-    /**
-     * The window to which responses are posted.
-     *
-     * Defaults to the `source` of the inbound message event. Pass the kit iframe's
-     * `contentWindow` explicitly to further restrict which window receives responses.
-     */
-    targetWindow?: Window;
-    /**
-     * The window on which to listen for inbound `message` events.
-     *
-     * Defaults to the global `window`. Override in tests or if the handler should
-     * listen on a specific frame's window.
-     */
-    listenerWindow?: Window & typeof globalThis;
-    /**
-     * Optional hook to subscribe to Brainy change events and forward them to the kit iframe.
-     *
-     * Called once when the handler is mounted. The provided `emit` callback posts a
-     * `brainy:event` message to the kit iframe whenever a Brainy change fires. Return an
-     * unsubscribe function; it will be called on `dispose()`.
-     *
-     * @param emit - Call this with each {@link BrainyChangeEvent} to forward it to the iframe.
-     * @returns An unsubscribe function called on `dispose()`.
-     *
-     * @example
-     * ```typescript
-     * createBrainyPostMessageHandler({
-     *   resolveBrain: () => pool.forUser(user.emailHash, workspaceId),
-     *   allowedOrigin: 'null',
-     *   targetWindow: iframe.contentWindow!,
-     *   subscribeToEvents: (emit) => {
-     *     const off = brainyChangeEmitter.on('change', emit)
-     *     return off
-     *   },
-     * })
-     * ```
-     */
-    subscribeToEvents?: (emit: (event: BrainyChangeEvent) => void) => () => void;
-}
-/**
- * A mounted PostMessage handler. Call `dispose()` when the kit iframe is torn down
- * to remove the message listener and prevent memory leaks.
- */
-export interface BrainyPostMessageHandler {
-    /**
-     * Remove the `message` event listener from the listener window.
-     *
-     * Call this when the associated kit iframe is unmounted or navigated away.
-     */
-    dispose(): void;
-}
-/**
- * Mount a PostMessage handler in the parent Workshop frame.
- *
- * Listens for `brainy:request` messages from kit iframes, dispatches each call to
- * the resolved Brainy instance via a {@link LocalTransport}, and posts the result
- * back as a `brainy:response` message.
- *
- * @param config - Handler configuration including brain resolver and allowed origin.
- * @returns A {@link BrainyPostMessageHandler} with a `dispose()` method.
- *
- * @example
- * ```typescript
- * const handler = createBrainyPostMessageHandler({
- *   resolveBrain: () => pool.forUser(user.emailHash, workspaceId),
- *   allowedOrigin: 'null',  // WebContainer iframes report origin 'null'
- *   targetWindow: iframe.contentWindow!,
- * })
- *
- * // On iframe unmount:
- * handler.dispose()
- * ```
- */
-export declare function createBrainyPostMessageHandler(config: BrainyPostMessageHandlerConfig): BrainyPostMessageHandler;
-//# sourceMappingURL=postmessage-handler.d.ts.map

package/dist/server/postmessage-handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postmessage-handler.d.ts","sourceRoot":"","sources":["../../src/server/postmessage-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAG/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAMpE;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IAE1D;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAA;IAErB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,UAAU,CAAA;IAE3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CA2D1B"}