@soulcraft/sdk 2.0.0 → 2.0.2

package/dist/server/postmessage-handler.js

@@ -1,138 +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 { LocalTransport } from '../transports/local.js';
-// ─────────────────────────────────────────────────────────────────────────────
-// Factory
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * 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 function createBrainyPostMessageHandler(config) {
-    const listenerWin = config.listenerWindow ?? window;
-    async function _handleMessage(event) {
-        // Validate origin.
-        if (config.allowedOrigin !== '*' && event.origin !== config.allowedOrigin)
-            return;
-        const data = event.data;
-        if (!data || data.type !== 'brainy:request' || !data.id)
-            return;
-        const { id, method, args } = data;
-        // Determine the window to reply to.
-        const replyTo = config.targetWindow ?? event.source;
-        if (!replyTo)
-            return;
-        let response;
-        try {
-            const brain = await config.resolveBrain(method);
-            const transport = new LocalTransport(brain);
-            const result = await transport.call(method, args);
-            response = { type: 'brainy:response', id, result };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            // Map known error names to codes the client can deserialize.
-            let code = 'RPC_ERROR';
-            if (err instanceof Error) {
-                if (err.name === 'SDKAuthError' || message.includes('Unauthorized'))
-                    code = 'AUTH_ERROR';
-                else if (err.name === 'SDKForbiddenError' || message.includes('Forbidden'))
-                    code = 'FORBIDDEN';
-                else if (err.name === 'BrainyMethodNotFoundError')
-                    code = 'METHOD_NOT_FOUND';
-            }
-            response = { type: 'brainy:response', id, error: { code, message } };
-        }
-        replyTo.postMessage(response, '*');
-    }
-    const listener = (event) => { void _handleMessage(event); };
-    listenerWin.addEventListener('message', listener);
-    // Wire Brainy change event forwarding to the kit iframe.
-    let _unsubscribeEvents;
-    if (config.subscribeToEvents) {
-        _unsubscribeEvents = config.subscribeToEvents((changeEvent) => {
-            // Resolve the reply target — prefer config.targetWindow, fall back to null (no-op).
-            const replyTo = config.targetWindow;
-            if (!replyTo)
-                return;
-            const msg = { type: 'brainy:event', event: changeEvent };
-            replyTo.postMessage(msg, '*');
-        });
-    }
-    return {
-        dispose() {
-            listenerWin.removeEventListener('message', listener);
-            _unsubscribeEvents?.();
-        },
-    };
-}
-//# sourceMappingURL=postmessage-handler.js.map

package/dist/server/postmessage-handler.js.map

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

package/dist/transports/http.d.ts

@@ -1,86 +0,0 @@
-/**
- * @module transports/http
- * @description HTTP transport — sends Brainy RPC calls as JSON POST requests.
- *
- * Posts to `{baseUrl}/api/brainy/rpc` with body `{ method, args }` and expects
- * `{ result }` or `{ error: { code, message } }` in the response.
- *
- * Works isomorphically in both the browser and server-side Bun/Node environments.
- * Uses `AbortController` for the configurable timeout (default 30 seconds).
- *
- * Change events are not supported by the HTTP transport — use the WebSocket
- * transport (`'ws'`) if real-time push events are required.
- *
- * @example
- * ```typescript
- * import { createSDK } from '@soulcraft/sdk/client'
- *
- * const sdk = createSDK({
- *   mode: 'client',
- *   product: 'workshop',
- *   transport: 'http',
- *   baseUrl: 'https://workshop.soulcraft.com',
- *   auth: 'cookie',  // send session cookies
- * })
- *
- * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
- * ```
- */
-import type { SDKTransport } from './transport.js';
-import type { BrainyChangeEvent } from '../modules/brainy/events.js';
-/**
- * Transport that sends Brainy RPC calls over HTTP POST.
- *
- * Each `call()` invocation is an independent HTTP request.
- * The transport is always considered "alive" — connectivity errors surface
- * as rejected promises from individual calls rather than a persistent state.
- */
-export declare class HttpTransport implements SDKTransport {
-    private readonly rpcUrl;
-    private readonly authToken;
-    private readonly credentials;
-    private readonly timeoutMs;
-    /**
-     * @param baseUrl - Base URL of the Brainy server, e.g. `'https://workshop.soulcraft.com'`.
-     * @param authToken - Optional capability token sent as `Authorization: Bearer <token>`.
-     * @param credentials - If `true`, include cookies with each request (same-origin browser use).
-     * @param timeoutMs - Request timeout in milliseconds. Default: 30 000.
-     */
-    constructor(baseUrl: string, authToken?: string, credentials?: boolean, timeoutMs?: number);
-    /**
-     * Sends the RPC call as a JSON POST and returns the result.
-     *
-     * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readdir'`).
-     * @param args - Positional arguments forwarded to the server.
-     * @returns The deserialized return value from Brainy.
-     * @throws {@link SDKTimeoutError} if the request exceeds `timeoutMs`.
-     * @throws {@link SDKAuthError} on HTTP 401.
-     * @throws {@link SDKForbiddenError} on HTTP 403.
-     * @throws {@link SDKRpcError} on any other non-ok HTTP response (5xx, 502, 503, etc.) or Brainy-level error.
-     * @throws {@link SDKDisconnectedError} on network failure.
-     */
-    call(method: string, args: unknown[]): Promise<unknown>;
-    /**
-     * No-op — HTTP transport does not support push change events.
-     *
-     * Use the WebSocket transport for real-time subscriptions.
-     *
-     * @param _handler - Unused.
-     */
-    onEvent(_handler: (event: BrainyChangeEvent) => void): void;
-    /**
-     * No-op — no listeners to remove.
-     *
-     * @param _handler - Unused.
-     */
-    offEvent(_handler: (event: BrainyChangeEvent) => void): void;
-    /**
-     * Always returns `true` — HTTP transport is stateless; errors surface per-call.
-     */
-    isAlive(): boolean;
-    /**
-     * No-op — HTTP transport has no persistent connection to close.
-     */
-    close(): Promise<void>;
-}
-//# sourceMappingURL=http.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AA8BpE;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,UAAQ,EACnB,SAAS,SAAS;IAQpB;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA+C7D;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI3D;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI5D;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/transports/http.js

@@ -1,137 +0,0 @@
-/**
- * @module transports/http
- * @description HTTP transport — sends Brainy RPC calls as JSON POST requests.
- *
- * Posts to `{baseUrl}/api/brainy/rpc` with body `{ method, args }` and expects
- * `{ result }` or `{ error: { code, message } }` in the response.
- *
- * Works isomorphically in both the browser and server-side Bun/Node environments.
- * Uses `AbortController` for the configurable timeout (default 30 seconds).
- *
- * Change events are not supported by the HTTP transport — use the WebSocket
- * transport (`'ws'`) if real-time push events are required.
- *
- * @example
- * ```typescript
- * import { createSDK } from '@soulcraft/sdk/client'
- *
- * const sdk = createSDK({
- *   mode: 'client',
- *   product: 'workshop',
- *   transport: 'http',
- *   baseUrl: 'https://workshop.soulcraft.com',
- *   auth: 'cookie',  // send session cookies
- * })
- *
- * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
- * ```
- */
-import { SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, } from '../modules/brainy/errors.js';
-/**
- * Transport that sends Brainy RPC calls over HTTP POST.
- *
- * Each `call()` invocation is an independent HTTP request.
- * The transport is always considered "alive" — connectivity errors surface
- * as rejected promises from individual calls rather than a persistent state.
- */
-export class HttpTransport {
-    rpcUrl;
-    authToken;
-    credentials;
-    timeoutMs;
-    /**
-     * @param baseUrl - Base URL of the Brainy server, e.g. `'https://workshop.soulcraft.com'`.
-     * @param authToken - Optional capability token sent as `Authorization: Bearer <token>`.
-     * @param credentials - If `true`, include cookies with each request (same-origin browser use).
-     * @param timeoutMs - Request timeout in milliseconds. Default: 30 000.
-     */
-    constructor(baseUrl, authToken, credentials = false, timeoutMs = 30_000) {
-        this.rpcUrl = `${baseUrl.replace(/\/$/, '')}/api/brainy/rpc`;
-        this.authToken = authToken;
-        this.credentials = credentials;
-        this.timeoutMs = timeoutMs;
-    }
-    /**
-     * Sends the RPC call as a JSON POST and returns the result.
-     *
-     * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readdir'`).
-     * @param args - Positional arguments forwarded to the server.
-     * @returns The deserialized return value from Brainy.
-     * @throws {@link SDKTimeoutError} if the request exceeds `timeoutMs`.
-     * @throws {@link SDKAuthError} on HTTP 401.
-     * @throws {@link SDKForbiddenError} on HTTP 403.
-     * @throws {@link SDKRpcError} on any other non-ok HTTP response (5xx, 502, 503, etc.) or Brainy-level error.
-     * @throws {@link SDKDisconnectedError} on network failure.
-     */
-    async call(method, args) {
-        const abort = new AbortController();
-        const timer = setTimeout(() => abort.abort(), this.timeoutMs);
-        const headers = { 'Content-Type': 'application/json' };
-        if (this.authToken)
-            headers['Authorization'] = `Bearer ${this.authToken}`;
-        const body = { method, args };
-        let response;
-        try {
-            response = await fetch(this.rpcUrl, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(body),
-                credentials: this.credentials ? 'include' : 'omit',
-                signal: abort.signal,
-            });
-        }
-        catch (err) {
-            clearTimeout(timer);
-            if (err instanceof DOMException && err.name === 'AbortError') {
-                throw new SDKTimeoutError(method);
-            }
-            throw new SDKDisconnectedError(err);
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        if (response.status === 401)
-            throw new SDKAuthError();
-        if (response.status === 403)
-            throw new SDKForbiddenError();
-        if (!response.ok) {
-            throw new SDKRpcError(`HTTP_${response.status}`, `SDK: server returned HTTP ${response.status} — the service may be temporarily unavailable`);
-        }
-        const json = (await response.json());
-        if ('error' in json && json.error) {
-            throw new SDKRpcError(json.error.code, json.error.message);
-        }
-        return json.result;
-    }
-    /**
-     * No-op — HTTP transport does not support push change events.
-     *
-     * Use the WebSocket transport for real-time subscriptions.
-     *
-     * @param _handler - Unused.
-     */
-    onEvent(_handler) {
-        // HTTP is stateless — no server push; use WsTransport for change events.
-    }
-    /**
-     * No-op — no listeners to remove.
-     *
-     * @param _handler - Unused.
-     */
-    offEvent(_handler) {
-        // Nothing to remove for HTTP transport.
-    }
-    /**
-     * Always returns `true` — HTTP transport is stateless; errors surface per-call.
-     */
-    isAlive() {
-        return true;
-    }
-    /**
-     * No-op — HTTP transport has no persistent connection to close.
-     */
-    async close() {
-        // Stateless — no connection to close.
-    }
-}
-//# sourceMappingURL=http.js.map

package/dist/transports/http.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,GACZ,MAAM,6BAA6B,CAAA;AAuBpC;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,CAAQ;IACd,SAAS,CAAoB;IAC7B,WAAW,CAAS;IACpB,SAAS,CAAQ;IAElC;;;;;OAKG;IACH,YACE,OAAe,EACf,SAAkB,EAClB,WAAW,GAAG,KAAK,EACnB,SAAS,GAAG,MAAM;QAElB,IAAI,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAA;QAC5D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,IAAe;QACxC,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAE7D,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA;QAC9E,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,SAAS,EAAE,CAAA;QAEzE,MAAM,IAAI,GAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;QAE7C,IAAI,QAAkB,CAAA;QACtB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE;gBAClC,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM;gBAClD,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC7D,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,CAAA;YACnC,CAAC;YACD,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAA;QACrC,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,YAAY,EAAE,CAAA;QACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAA;QAE1D,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,WAAW,CACnB,QAAQ,QAAQ,CAAC,MAAM,EAAE,EACzB,6BAA6B,QAAQ,CAAC,MAAM,+CAA+C,CAC5F,CAAA;QACH,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAgB,CAAA;QAEnD,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAC5D,CAAC;QAED,OAAQ,IAA2B,CAAC,MAAM,CAAA;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,QAA4C;QAClD,yEAAyE;IAC3E,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,QAA4C;QACnD,wCAAwC;IAC1C,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,sCAAsC;IACxC,CAAC;CACF"}

package/dist/transports/postmessage.d.ts

@@ -1,159 +0,0 @@
-/**
- * @module transports/postmessage
- * @description PostMessage transport — sends Brainy RPC calls from a child iframe to its
- * parent frame via `window.postMessage`.
- *
- * Designed for Workshop kit apps running inside WebContainer iframes. The kit app calls
- * Brainy methods as normal via `createBrainyProxy(transport)`, and each call is forwarded
- * to the parent Workshop frame which owns the actual Brainy instance.
- *
- * ## Wire protocol
- *
- * **Request** (kit iframe → parent):
- * ```json
- * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{ "query": "..." }] }
- * ```
- *
- * **Response** (parent → kit iframe):
- * ```json
- * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
- * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "RPC_ERROR", "message": "..." } }
- * ```
- *
- * The `id` field correlates each response to its originating request. Pending calls are
- * resolved or rejected when the matching response arrives.
- *
- * ## Usage
- *
- * ```typescript
- * // Kit app (iframe):
- * import { PostMessageTransport, createBrainyProxy } from '@soulcraft/sdk/client'
- *
- * const transport = new PostMessageTransport()
- * const brainy = createBrainyProxy(transport)
- *
- * const results = await brainy.find({ query: 'candle inventory', limit: 10 })
- * ```
- *
- * The parent frame must mount a `createBrainyPostMessageHandler` from `@soulcraft/sdk/server`
- * to receive and respond to these messages.
- *
- * ## Security
- *
- * Messages are sent to `targetOrigin`. Always pass the explicit Workshop origin
- * (e.g. `'https://workshop.soulcraft.com'`). Using `'*'` broadcasts to any origin
- * and must never be used in production — it leaks Brainy RPC responses to third-party
- * frames. The parent handler validates `event.source` and `event.origin` before dispatching.
- */
-import type { SDKTransport } from './transport.js';
-import type { BrainyChangeEvent } from '../modules/brainy/events.js';
-/** A Brainy RPC request posted from the kit iframe to the parent. */
-export interface PostMessageRequest {
-    type: 'brainy:request';
-    id: string;
-    method: string;
-    args: unknown[];
-}
-/** A successful Brainy RPC response posted from the parent to the kit iframe. */
-export interface PostMessageSuccessResponse {
-    type: 'brainy:response';
-    id: string;
-    result: unknown;
-}
-/** An error Brainy RPC response posted from the parent to the kit iframe. */
-export interface PostMessageErrorResponse {
-    type: 'brainy:response';
-    id: string;
-    error: {
-        code: string;
-        message: string;
-    };
-}
-/** Union of all response shapes. */
-export type PostMessageResponse = PostMessageSuccessResponse | PostMessageErrorResponse;
-/** A real-time change event forwarded from the parent frame to the kit iframe. */
-export interface PostMessageEventMessage {
-    type: 'brainy:event';
-    event: BrainyChangeEvent;
-}
-/** Minimal window-like interface required by the transport. */
-export interface PostMessageWindow {
-    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
-    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
-    postMessage(message: unknown, targetOrigin: string): void;
-    readonly parent: PostMessageWindow;
-}
-/**
- * PostMessage transport for kit apps running inside Workshop WebContainer iframes.
- *
- * Each `call()` posts a `brainy:request` message to `window.parent` and waits for
- * a matching `brainy:response` message. Responses are correlated by a UUID `id` field
- * generated per request.
- *
- * The transport installs a single `message` listener on `window` at construction time
- * and removes it when `close()` is called.
- */
-export declare class PostMessageTransport implements SDKTransport {
-    private readonly _targetOrigin;
-    private readonly _timeoutMs;
-    private readonly _pending;
-    private readonly _eventHandlers;
-    private _closed;
-    private readonly _messageListener;
-    private readonly _listenerWindow;
-    private readonly _parentWindow;
-    /**
-     * @param targetOrigin - The origin to which requests are sent.
-     *   Must be an explicit origin (e.g. `'https://workshop.soulcraft.com'`).
-     *   Never use `'*'` in production — it broadcasts RPC responses to any origin.
-     * @param timeoutMs - Per-call timeout in milliseconds. Default: 30 000.
-     * @param listenerWindow - Window on which to listen for responses. Defaults to `window`.
-     *   Pass a custom object in tests or non-browser environments.
-     * @param parentWindow - Window to which requests are posted. Defaults to `window.parent`.
-     *   Pass a custom object in tests or non-browser environments.
-     */
-    constructor(targetOrigin: string, timeoutMs?: number, listenerWindow?: PostMessageWindow, parentWindow?: PostMessageWindow);
-    private _handleMessage;
-    private _generateId;
-    /**
-     * Dispatch a Brainy RPC call via `window.parent.postMessage`.
-     *
-     * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readFile'`).
-     * @param args - Positional arguments forwarded to Brainy on the parent frame.
-     * @returns A Promise that resolves with the Brainy method's return value.
-     * @throws {@link SDKDisconnectedError} if the transport has been closed.
-     * @throws {@link SDKTimeoutError} if no response arrives within `timeoutMs`.
-     * @throws {@link SDKAuthError} if the parent responds with an auth error.
-     * @throws {@link SDKRpcError} if the parent responds with a Brainy-level error.
-     */
-    call(method: string, args: unknown[]): Promise<unknown>;
-    /**
-     * Register a handler for real-time Brainy change events.
-     *
-     * Change events are forwarded from the parent frame via `brainy:event` messages.
-     * The parent handler posts these when Brainy fires a data change.
-     *
-     * @param handler - Called with each {@link BrainyChangeEvent}.
-     */
-    onEvent(handler: (event: BrainyChangeEvent) => void): void;
-    /**
-     * Remove a previously registered change event handler.
-     *
-     * @param handler - The same function reference passed to {@link onEvent}.
-     */
-    offEvent(handler: (event: BrainyChangeEvent) => void): void;
-    /**
-     * Returns `true` when the transport is open.
-     *
-     * PostMessage is always available as long as the transport has not been closed —
-     * it relies on `window.parent` which is always present inside an iframe.
-     */
-    isAlive(): boolean;
-    /**
-     * Close the transport, removing the message listener and rejecting all pending calls.
-     *
-     * After calling `close()`, any further `call()` invocations throw `SDKDisconnectedError`.
-     */
-    close(): Promise<void>;
-}
-//# sourceMappingURL=postmessage.d.ts.map

package/dist/transports/postmessage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postmessage.d.ts","sourceRoot":"","sources":["../../src/transports/postmessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAapE,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAA;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,OAAO,EAAE,CAAA;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,iBAAiB,CAAA;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,iBAAiB,CAAA;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,oCAAoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,wBAAwB,CAAA;AAEvF,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,cAAc,CAAA;IACpB,KAAK,EAAE,iBAAiB,CAAA;CACzB;AAaD,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IAChF,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IACnF,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACzD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgD;IAC/E,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD;;;;;;;;;OASG;gBAED,YAAY,EAAE,MAAM,EACpB,SAAS,SAAS,EAClB,cAAc,CAAC,EAAE,iBAAiB,EAClC,YAAY,CAAC,EAAE,iBAAiB;IAalC,OAAO,CAAC,cAAc;IAuCtB,OAAO,CAAC,WAAW;IAWnB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB7D;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI1D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI3D;;;;;OAKG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAa7B"}