@soulcraft/sdk 1.6.2 → 2.0.0

package/dist/server/namespace-router.js

@@ -0,0 +1,262 @@
+/**
+ * @module server/namespace-router
+ * @description Universal namespace-aware RPC dispatcher for the Soulcraft SDK.
+ *
+ * Receives requests in the {@link SoulcraftRPC} envelope format, authenticates the
+ * caller, resolves the target namespace, and dispatches to the appropriate handler.
+ *
+ * ## Dispatch model
+ *
+ * - `brainy` / `brainy.vfs` / `brainy.versions` → {@link LocalTransport} dispatch
+ *   against the resolved Brainy instance (same proven RPC path as SDK 1.x).
+ * - All other namespaces → provider-based dispatch. Each namespace's provider is a
+ *   plain object whose methods match the namespace contract in `namespaces.ts`.
+ *
+ * ## Streaming
+ *
+ * When `stream: true` is set on the request, the handler is expected to return an
+ * `AsyncIterable`. The router converts each yielded value into a
+ * {@link SoulcraftRPCStream} frame and delivers it via the transport-appropriate
+ * mechanism (SSE, PostMessage chunks, or WebSocket frames).
+ *
+ * ## Error handling
+ *
+ * All errors are caught at the dispatch level and returned as `SoulcraftRPCResponse`
+ * with an `error` field. Handler code does not need to wrap logic in try/catch.
+ *
+ * @example Hono integration
+ * ```typescript
+ * import { createNamespaceRouter } from '@soulcraft/sdk/server'
+ *
+ * const router = createNamespaceRouter({
+ *   resolveBrain: async (ctx) => pool.forUser(ctx.userId, ctx.workspaceId),
+ *   authenticate: async (ctx) => verifySession(ctx.request),
+ *   providers: { chat: chatProvider, graph: graphProvider },
+ * })
+ *
+ * const response = await router.dispatch({ ns: 'brainy', method: 'find', args: [...] }, requestContext)
+ * ```
+ */
+import { LocalTransport } from '../transports/local.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Brainy namespace prefixes
+// ─────────────────────────────────────────────────────────────────────────────
+/** Namespaces dispatched directly to Brainy via LocalTransport. */
+const BRAINY_NAMESPACES = new Set(['brainy', 'brainy.vfs', 'brainy.versions']);
+/**
+ * Checks if a namespace should be dispatched to Brainy's LocalTransport.
+ *
+ * @param ns - The namespace string.
+ * @returns `true` if the namespace is a Brainy sub-namespace.
+ */
+function isBrainyNamespace(ns) {
+    return BRAINY_NAMESPACES.has(ns) || ns.startsWith('brainy.');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates a namespace-aware RPC router that dispatches to Brainy or provider
+ * handler methods based on the `ns` field in the request.
+ *
+ * @param config - Router configuration.
+ * @returns A {@link NamespaceRouter} with a `dispatch()` method.
+ *
+ * @example
+ * ```typescript
+ * const router = createNamespaceRouter({
+ *   resolveBrain: (ctx) => pool.forUser(ctx.user!.emailHash, ctx.workspaceId),
+ *   authenticate: (ctx) => verifySession(ctx.request),
+ *   providers: {
+ *     chat: chatHandler,
+ *     graph: graphHandler,
+ *   },
+ * })
+ *
+ * const result = await router.dispatch(
+ *   { id: '1', ns: 'brainy', method: 'find', args: [{ query: 'test' }] },
+ *   request,
+ * )
+ * ```
+ */
+export function createNamespaceRouter(config) {
+    const { resolveBrain, authenticate, authorize, providers, blockedBrainyMethods = [], } = config;
+    return {
+        async dispatch(rpc, request) {
+            const { id, ns, method, args, stream } = rpc;
+            // ── Extract workspace ID ──────────────────────────────────────────
+            const workspaceId = _extractWorkspaceId(request);
+            // ── Build request context ──────────────────────────────────────────
+            const ctx = { request, user: null, workspaceId };
+            // ── Authenticate ──────────────────────────────────────────────────
+            try {
+                const user = await authenticate(ctx);
+                if (!user) {
+                    return _errorResponse(id, 401, 'UNAUTHORIZED', 'Authentication required');
+                }
+                ctx.user = user;
+            }
+            catch (err) {
+                console.error('[SDK/router] authenticate threw:', err);
+                return _errorResponse(id, 401, 'AUTH_ERROR', 'Authentication failed');
+            }
+            // ── Authorize ─────────────────────────────────────────────────────
+            if (authorize) {
+                try {
+                    const allowed = await authorize(ns, method, args, ctx.user);
+                    if (!allowed) {
+                        return _errorResponse(id, 403, 'FORBIDDEN', `Not authorized: ${ns}.${method}`);
+                    }
+                }
+                catch (err) {
+                    console.error('[SDK/router] authorize threw:', err);
+                    return _errorResponse(id, 403, 'FORBIDDEN', 'Authorization check failed');
+                }
+            }
+            // ── Dispatch: Brainy namespaces ───────────────────────────────────
+            if (isBrainyNamespace(ns)) {
+                return _dispatchBrainy(id, ns, method, args, ctx, resolveBrain, blockedBrainyMethods);
+            }
+            // ── Dispatch: Provider namespaces ──────────────────────────────────
+            const provider = providers[ns];
+            if (!provider) {
+                return _errorResponse(id, 404, 'NAMESPACE_NOT_FOUND', `Namespace '${ns}' is not registered`);
+            }
+            const handlerFn = provider[method];
+            if (typeof handlerFn !== 'function') {
+                return _errorResponse(id, 404, 'METHOD_NOT_FOUND', `Method '${ns}.${method}' does not exist`);
+            }
+            // Build handler context for the provider method
+            let brain;
+            try {
+                brain = await resolveBrain(ctx);
+            }
+            catch (err) {
+                console.error('[SDK/router] resolveBrain threw for provider dispatch:', err);
+                return _errorResponse(id, 503, 'BRAIN_UNAVAILABLE', 'Brainy instance not available');
+            }
+            const handlerCtx = {
+                user: ctx.user,
+                workspaceId,
+                brain,
+                request,
+            };
+            try {
+                // Invoke the provider method with the RPC args + handler context.
+                // The handler context is always the last argument.
+                const result = await handlerFn(...args, handlerCtx);
+                // Check if the result is an async iterable (streaming response).
+                if (stream && result != null && typeof result === 'object' && Symbol.asyncIterator in result) {
+                    return {
+                        type: 'stream',
+                        id,
+                        iterable: result,
+                    };
+                }
+                return {
+                    type: 'response',
+                    response: { id, result },
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[SDK/router] ${ns}.${method} threw:`, err);
+                return _errorResponse(id, 500, 'RPC_ERROR', message);
+            }
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Brainy dispatch
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Dispatches a request to the Brainy namespace via LocalTransport.
+ *
+ * The method path is constructed by stripping the `brainy` prefix and prepending
+ * the sub-namespace. For example:
+ * - `ns: 'brainy'`, `method: 'find'` → `transport.call('find', args)`
+ * - `ns: 'brainy.vfs'`, `method: 'readdir'` → `transport.call('vfs.readdir', args)`
+ *
+ * @param id - Request ID for the response.
+ * @param ns - The Brainy namespace (e.g. `'brainy'`, `'brainy.vfs'`).
+ * @param method - The method within the namespace.
+ * @param args - Positional arguments.
+ * @param ctx - The request context with authenticated user.
+ * @param resolveBrain - Callback to resolve the Brainy instance.
+ * @param blockedMethods - Methods that are blocked.
+ * @returns A dispatch result.
+ */
+async function _dispatchBrainy(id, ns, method, args, ctx, resolveBrain, blockedMethods) {
+    // Build the full method path for LocalTransport.
+    // 'brainy' → method as-is (e.g. 'find')
+    // 'brainy.vfs' → 'vfs.{method}' (e.g. 'vfs.readdir')
+    // 'brainy.versions' → 'versions.{method}'
+    const subNs = ns === 'brainy' ? '' : ns.slice('brainy.'.length);
+    const transportMethod = subNs ? `${subNs}.${method}` : method;
+    // Check blocklist
+    if (blockedMethods.includes(transportMethod)) {
+        return _errorResponse(id, 403, 'FORBIDDEN', `Method '${transportMethod}' is not available via RPC`);
+    }
+    // Resolve Brainy instance
+    let brain;
+    try {
+        brain = await resolveBrain(ctx);
+    }
+    catch (err) {
+        console.error('[SDK/router] resolveBrain threw:', err);
+        return _errorResponse(id, 503, 'BRAIN_UNAVAILABLE', 'Brainy instance not available');
+    }
+    // Dispatch via LocalTransport (same proven path as SDK 1.x)
+    const transport = new LocalTransport(brain);
+    try {
+        const result = await transport.call(transportMethod, args);
+        return {
+            type: 'response',
+            response: { id, result },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return _errorResponse(id, 500, 'RPC_ERROR', message);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Builds an error dispatch result.
+ *
+ * @param id - Request ID.
+ * @param _status - HTTP-like status code (for logging; not in the envelope).
+ * @param code - Machine-readable error code.
+ * @param message - Human-readable error description.
+ * @returns A response dispatch result with the error.
+ */
+function _errorResponse(id, _status, code, message) {
+    return {
+        type: 'response',
+        response: { id, error: { code, message } },
+    };
+}
+/**
+ * Extracts the workspace ID from the request.
+ *
+ * Checks the `X-Workspace-Id` header first, then falls back to the `workspaceId`
+ * query parameter (necessary for SSE which doesn't support custom headers).
+ *
+ * @param request - The incoming HTTP request.
+ * @returns The workspace ID, or empty string if not present.
+ */
+function _extractWorkspaceId(request) {
+    const fromHeader = request.headers.get('x-workspace-id');
+    if (fromHeader)
+        return fromHeader;
+    try {
+        const url = new URL(request.url);
+        return url.searchParams.get('workspaceId') ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=namespace-router.js.map

package/dist/server/namespace-router.js.map

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

package/dist/transports/http-namespace.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @module transports/http-namespace
+ * @description Namespace-aware HTTP transport — sends RPC calls as JSON POST to `/api/rpc`
+ * with the unified `{ ns, method, args }` envelope.
+ *
+ * This is the Symmetrical SDK 2.0 replacement for {@link HttpTransport}, which
+ * only supports the `brainy` namespace via `{ method, args }` at `/api/brainy/rpc`.
+ *
+ * For streaming responses, the transport reads the response as SSE
+ * (`text/event-stream`) and yields each `data:` line as a chunk.
+ *
+ * @example
+ * ```typescript
+ * import { HttpNamespaceTransport } from '@soulcraft/sdk/client'
+ * import { createSoulcraftProxy } from '@soulcraft/sdk/client'
+ *
+ * const transport = new HttpNamespaceTransport('https://workshop.soulcraft.com', {
+ *   credentials: true,
+ * })
+ * const soulcraft = createSoulcraftProxy(transport)
+ *
+ * const graph = await soulcraft.graph.getData()
+ * const results = await soulcraft.brainy.find({ query: 'candles' })
+ * ```
+ */
+import type { NamespaceTransport } from '../client/namespace-proxy.js';
+/**
+ * Options for {@link HttpNamespaceTransport}.
+ */
+export interface HttpNamespaceTransportOptions {
+    /**
+     * Optional capability token sent as `Authorization: Bearer <token>`.
+     * Mutually exclusive with `credentials: true` (cookie auth).
+     */
+    authToken?: string | undefined;
+    /**
+     * If `true`, include cookies with each request (same-origin browser use).
+     *
+     * @default false
+     */
+    credentials?: boolean | undefined;
+    /**
+     * Per-request timeout in milliseconds.
+     *
+     * @default 30000
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Custom headers to include with every request (e.g. `X-Workspace-Id`).
+     */
+    headers?: Record<string, string> | undefined;
+}
+/**
+ * Namespace-aware HTTP transport for Soulcraft SDK 2.0.
+ *
+ * Posts to `{baseUrl}/api/rpc` with the unified RPC envelope.
+ * Supports both JSON responses and SSE streaming.
+ */
+export declare class HttpNamespaceTransport implements NamespaceTransport {
+    private readonly _rpcUrl;
+    private readonly _authToken;
+    private readonly _credentials;
+    private readonly _timeoutMs;
+    private readonly _headers;
+    private _closed;
+    /**
+     * @param baseUrl - Base URL of the Soulcraft server (e.g. `'https://workshop.soulcraft.com'`).
+     * @param options - Transport options.
+     */
+    constructor(baseUrl: string, options?: HttpNamespaceTransportOptions);
+    /**
+     * Dispatch a namespace-aware RPC call over HTTP POST.
+     *
+     * @param ns - Target namespace.
+     * @param method - Method within the namespace.
+     * @param args - Positional arguments.
+     * @returns The handler's return value.
+     */
+    callNs(ns: string, method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Dispatch a streaming namespace-aware RPC call.
+     *
+     * Sends the request with `stream: true` and reads the response as SSE.
+     *
+     * @param ns - Target namespace.
+     * @param method - Method within the namespace.
+     * @param args - Positional arguments.
+     * @returns An async iterable of response chunks.
+     */
+    callNsStream(ns: string, method: string, args: unknown[]): AsyncIterable<unknown>;
+    /** Returns `true` when the transport is open. */
+    isAlive(): boolean;
+    /** Close the transport. Further calls throw `SDKDisconnectedError`. */
+    close(): Promise<void>;
+}
+/**
+ * Namespace-aware PostMessage transport for kit apps in WebContainer iframes.
+ *
+ * Uses the unified `soulcraft:request` / `soulcraft:response` / `soulcraft:stream`
+ * wire protocol instead of the legacy `brainy:request` + `workshop:request` split.
+ */
+export declare class PostMessageNamespaceTransport implements NamespaceTransport {
+    private readonly _targetOrigin;
+    private readonly _timeoutMs;
+    private readonly _pending;
+    private readonly _pendingStreams;
+    private _closed;
+    private readonly _messageListener;
+    private readonly _listenerWindow;
+    private readonly _parentWindow;
+    /**
+     * @param targetOrigin - The parent frame's origin for security.
+     * @param timeoutMs - Per-call timeout. Default: 60 000.
+     * @param listenerWindow - Window for message events. Defaults to `window`.
+     * @param parentWindow - Window to post messages to. Defaults to `window.parent`.
+     */
+    constructor(targetOrigin: string, timeoutMs?: number, listenerWindow?: {
+        addEventListener: Function;
+        removeEventListener: Function;
+    }, parentWindow?: {
+        postMessage: Function;
+    });
+    private _handleMessage;
+    private _streamTimeout;
+    /**
+     * Dispatch a namespace-aware RPC call via PostMessage.
+     *
+     * Posts a `soulcraft:request` message to the parent window and waits for a
+     * matching `soulcraft:response` message keyed by request ID.
+     *
+     * @param ns - Target namespace (e.g. `'brainy'`, `'chat'`).
+     * @param method - Method within the namespace.
+     * @param args - Positional arguments.
+     * @returns The handler's return value from the parent frame.
+     * @throws {SDKDisconnectedError} If the transport is closed.
+     * @throws {SDKTimeoutError} If no response arrives within `timeoutMs`.
+     * @throws {SDKRpcError} If the parent frame returns an error.
+     *
+     * @example
+     * ```typescript
+     * const graph = await transport.callNs('graph', 'getData', [])
+     * ```
+     */
+    callNs(ns: string, method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Dispatch a streaming namespace-aware RPC call via PostMessage.
+     *
+     * Posts a `soulcraft:request` message with `stream: true`. The parent frame
+     * responds with a series of `soulcraft:stream` messages, each containing a
+     * `chunk`, `done`, or `error` field. Chunks are buffered and yielded through
+     * the returned async iterable.
+     *
+     * @param ns - Target namespace.
+     * @param method - Method within the namespace.
+     * @param args - Positional arguments.
+     * @returns An async iterable that yields response chunks.
+     * @throws {SDKDisconnectedError} If the transport is closed.
+     * @throws {SDKRpcError} If the stream receives an error frame.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of transport.callNsStream('chat', 'sendStreaming', [msg])) {
+     *   process.stdout.write(chunk.text)
+     * }
+     * ```
+     */
+    callNsStream(ns: string, method: string, args: unknown[]): AsyncIterable<unknown>;
+    /**
+     * Returns `true` when the transport has an active connection.
+     *
+     * Once {@link close} is called, this returns `false` permanently.
+     */
+    isAlive(): boolean;
+    /**
+     * Close the transport and clean up all pending calls.
+     *
+     * Removes the global `message` event listener, rejects all pending call
+     * promises with {@link SDKDisconnectedError}, and terminates all active
+     * streams. Further calls to {@link callNs} or {@link callNsStream} will
+     * throw immediately.
+     */
+    close(): Promise<void>;
+}
+/**
+ * @description SDK 2.0 canonical HTTP transport. Alias for {@link HttpNamespaceTransport}.
+ *
+ * Sends RPC calls as JSON POST to `/api/rpc` with the unified `{ ns, method, args }` envelope.
+ * Supports streaming via SSE.
+ *
+ * @example
+ * ```typescript
+ * import { HttpTransport, createSoulcraftProxy } from '@soulcraft/sdk/client'
+ * const sdk = createSoulcraftProxy(new HttpTransport('/api'))
+ * ```
+ */
+export { HttpNamespaceTransport as HttpRpcTransport };
+/**
+ * @description SDK 2.0 canonical PostMessage transport. Alias for {@link PostMessageNamespaceTransport}.
+ *
+ * Uses the unified `soulcraft:request` / `soulcraft:response` / `soulcraft:stream`
+ * wire protocol for kit apps in WebContainer iframes.
+ *
+ * @example
+ * ```typescript
+ * import { PostMessageRpcTransport, createSoulcraftProxy } from '@soulcraft/sdk/client'
+ * const sdk = createSoulcraftProxy(new PostMessageRpcTransport(parentOrigin))
+ * ```
+ */
+export { PostMessageNamespaceTransport as PostMessageRpcTransport };
+//# sourceMappingURL=http-namespace.d.ts.map

package/dist/transports/http-namespace.d.ts.map

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