@soulcraft/sdk 1.0.0

package/dist/transports/http.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 SDKDisconnectedError} on network failure.
+     * @throws {@link SDKRpcError} if the server returns a Brainy-level error.
+     */
+    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

@@ -0,0 +1 @@
+{"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;IAwC7D;;;;;;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

@@ -0,0 +1,134 @@
+/**
+ * @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 SDKDisconnectedError} on network failure.
+     * @throws {@link SDKRpcError} if the server returns a Brainy-level error.
+     */
+    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();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status === 401)
+            throw new SDKAuthError();
+        if (response.status === 403)
+            throw new SDKForbiddenError();
+        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

@@ -0,0 +1 @@
+{"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,EAAE,CAAA;QAClC,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,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/local.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @module transports/local
+ * @description Local transport — wraps a native Brainy instance with zero overhead.
+ *
+ * Used server-side when the Brainy instance lives in the same process as the
+ * caller. Method calls are dispatched by traversing the Brainy object's property
+ * chain (split on `.`) and invoking the resolved function directly — no
+ * serialization, no network, no latency.
+ *
+ * The server-mode `BrainyInstancePool` uses this transport internally: it resolves
+ * the correct Brainy instance for the authenticated user/tenant and wraps it in a
+ * `LocalTransport` before handing it to the Brainy proxy.
+ *
+ * @example
+ * ```typescript
+ * import { createSDK } from '@soulcraft/sdk/server'
+ *
+ * // Server mode creates a LocalTransport automatically via the instance pool.
+ * const sdk = await createSDK({ mode: 'server', product: 'workshop', ... })
+ * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
+ * ```
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { SDKTransport } from './transport.js';
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+/**
+ * Transport that wraps a local Brainy instance with zero overhead.
+ *
+ * Dispatches calls by splitting the dot-separated method name on `.` and
+ * traversing the Brainy object graph. Handles both top-level methods (`'find'`)
+ * and sub-API methods (`'vfs.readdir'`, `'versions.list'`).
+ *
+ * Change events are not emitted by the local transport — mutations are
+ * synchronous from the perspective of the in-process caller.
+ */
+export declare class LocalTransport implements SDKTransport {
+    private readonly brain;
+    /**
+     * @param brain - A fully initialized Brainy instance.
+     */
+    constructor(brain: Brainy);
+    /**
+     * Resolves the method via property traversal and calls it with the given args.
+     *
+     * @param method - Dot-separated path into the Brainy object (e.g. `'vfs.readdir'`).
+     * @param args - Positional arguments forwarded to the resolved method.
+     * @returns Whatever the Brainy method returns.
+     * @throws {@link SDKMethodNotFoundError} if the method path does not resolve to a callable.
+     */
+    call(method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * No-op — local transport does not push change events.
+     *
+     * In-process mutations are synchronous; subscribers would be notified before
+     * the call even returns.
+     *
+     * @param _handler - Unused.
+     */
+    onEvent(_handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * No-op — local transport does not push change events.
+     *
+     * @param _handler - Unused.
+     */
+    offEvent(_handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Always returns `true` — the local Brainy instance is always reachable.
+     */
+    isAlive(): boolean;
+    /**
+     * No-op — the local Brainy instance lifecycle is managed by the server's
+     * instance pool, not by the transport.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=local.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/transports/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAGpE;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAE9B;;OAEG;gBACS,KAAK,EAAE,MAAM;IAIzB;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB7D;;;;;;;OAOG;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;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/transports/local.js

@@ -0,0 +1,101 @@
+/**
+ * @module transports/local
+ * @description Local transport — wraps a native Brainy instance with zero overhead.
+ *
+ * Used server-side when the Brainy instance lives in the same process as the
+ * caller. Method calls are dispatched by traversing the Brainy object's property
+ * chain (split on `.`) and invoking the resolved function directly — no
+ * serialization, no network, no latency.
+ *
+ * The server-mode `BrainyInstancePool` uses this transport internally: it resolves
+ * the correct Brainy instance for the authenticated user/tenant and wraps it in a
+ * `LocalTransport` before handing it to the Brainy proxy.
+ *
+ * @example
+ * ```typescript
+ * import { createSDK } from '@soulcraft/sdk/server'
+ *
+ * // Server mode creates a LocalTransport automatically via the instance pool.
+ * const sdk = await createSDK({ mode: 'server', product: 'workshop', ... })
+ * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
+ * ```
+ */
+import { SDKMethodNotFoundError } from '../modules/brainy/errors.js';
+/**
+ * Transport that wraps a local Brainy instance with zero overhead.
+ *
+ * Dispatches calls by splitting the dot-separated method name on `.` and
+ * traversing the Brainy object graph. Handles both top-level methods (`'find'`)
+ * and sub-API methods (`'vfs.readdir'`, `'versions.list'`).
+ *
+ * Change events are not emitted by the local transport — mutations are
+ * synchronous from the perspective of the in-process caller.
+ */
+export class LocalTransport {
+    brain;
+    /**
+     * @param brain - A fully initialized Brainy instance.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    /**
+     * Resolves the method via property traversal and calls it with the given args.
+     *
+     * @param method - Dot-separated path into the Brainy object (e.g. `'vfs.readdir'`).
+     * @param args - Positional arguments forwarded to the resolved method.
+     * @returns Whatever the Brainy method returns.
+     * @throws {@link SDKMethodNotFoundError} if the method path does not resolve to a callable.
+     */
+    async call(method, args) {
+        const parts = method.split('.');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let target = this.brain;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (part === undefined || typeof target !== 'object' || target === null) {
+                throw new SDKMethodNotFoundError(method);
+            }
+            target = target[part];
+        }
+        const methodName = parts[parts.length - 1];
+        if (methodName === undefined || typeof target[methodName] !== 'function') {
+            throw new SDKMethodNotFoundError(method);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        return target[methodName].apply(target, args);
+    }
+    /**
+     * No-op — local transport does not push change events.
+     *
+     * In-process mutations are synchronous; subscribers would be notified before
+     * the call even returns.
+     *
+     * @param _handler - Unused.
+     */
+    onEvent(_handler) {
+        // Local transport: mutations are synchronous in-process; no push needed.
+    }
+    /**
+     * No-op — local transport does not push change events.
+     *
+     * @param _handler - Unused.
+     */
+    offEvent(_handler) {
+        // Local transport: nothing to remove.
+    }
+    /**
+     * Always returns `true` — the local Brainy instance is always reachable.
+     */
+    isAlive() {
+        return true;
+    }
+    /**
+     * No-op — the local Brainy instance lifecycle is managed by the server's
+     * instance pool, not by the transport.
+     */
+    async close() {
+        // Instance lifecycle is managed externally by BrainyInstancePool.
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/transports/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/transports/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAEpE;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,CAAQ;IAE9B;;OAEG;IACH,YAAY,KAAa;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,IAAe;QACxC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC/B,8DAA8D;QAC9D,IAAI,MAAM,GAAQ,IAAI,CAAC,KAAK,CAAA;QAE5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;YACrB,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACxE,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAA;YAC1C,CAAC;YACD,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;QACvB,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAC1C,IAAI,UAAU,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,UAAU,EAAE,CAAC;YACzE,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAA;QAC1C,CAAC;QAED,6DAA6D;QAC7D,OAAQ,MAAM,CAAC,UAAU,CAAkC,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACjF,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,QAA4C;QAClD,yEAAyE;IAC3E,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,QAA4C;QACnD,sCAAsC;IACxC,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,kEAAkE;IACpE,CAAC;CACF"}

package/dist/transports/sse.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @module transports/sse
+ * @description SSE transport — receives server-pushed platform events via EventSource.
+ *
+ * Connects to `{baseUrl}/api/workspace/events` using the browser's native
+ * `EventSource` API and dispatches typed {@link BrainyChangeEvent} objects to
+ * registered listeners.
+ *
+ * This transport is **receive-only** — it does not support outbound RPC calls.
+ * Use it alongside the HTTP transport when you need live VFS and entity change
+ * events without the overhead of a persistent WebSocket.
+ *
+ * `EventSource` handles reconnection natively: the browser automatically
+ * retries after a connection drop using the server-sent `retry:` interval.
+ * Additional manual backoff is applied on error events to prevent thundering herd.
+ *
+ * @example
+ * ```typescript
+ * import { createSDK } from '@soulcraft/sdk/client'
+ *
+ * const sdk = createSDK({
+ *   mode: 'client',
+ *   product: 'venue',
+ *   transport: 'sse',
+ *   baseUrl: 'https://venue.soulcraft.com',
+ * })
+ *
+ * // Subscribe to live data changes (VFS writes, entity mutations, etc.)
+ * sdk.brainy.onDataChange((event) => {
+ *   if (event.event === 'update' && event.entity?.nounType === 'Booking') {
+ *     refreshBookingList()
+ *   }
+ * })
+ * ```
+ */
+import type { SDKTransport } from './transport.js';
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+/**
+ * Transport that receives platform change events via Server-Sent Events.
+ *
+ * RPC calls are not supported — `call()` throws immediately. For outbound
+ * operations pair this transport with an `HttpTransport` instance.
+ *
+ * Connect by calling `connect()`. The underlying `EventSource` will reconnect
+ * automatically on drop; `close()` permanently disconnects and prevents reconnects.
+ */
+export declare class SseTransport implements SDKTransport {
+    private readonly eventsUrl;
+    private readonly workspaceId;
+    private eventSource;
+    private readonly changeListeners;
+    private closed;
+    private reconnectAttempts;
+    private readonly maxReconnectAttempts;
+    private reconnectTimer;
+    /**
+     * @param baseUrl - Base URL of the SDK server, e.g. `'https://venue.soulcraft.com'`.
+     * @param workspaceId - Optional workspace ID added as `?workspaceId=` query param.
+     */
+    constructor(baseUrl: string, workspaceId?: string);
+    /**
+     * Not supported — SSE is a server-push-only transport.
+     *
+     * @throws {@link SDKError} always.
+     */
+    call(_method: string, _args: unknown[]): Promise<unknown>;
+    /**
+     * Registers a listener for real-time change events received from the server.
+     *
+     * @param handler - Called with each {@link BrainyChangeEvent} as it arrives.
+     */
+    onEvent(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Removes a previously registered change event listener.
+     *
+     * @param handler - The same function reference passed to {@link SseTransport.onEvent}.
+     */
+    offEvent(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Returns `true` when the `EventSource` is in the `OPEN` state.
+     */
+    isAlive(): boolean;
+    /**
+     * Permanently closes the SSE connection and cancels any pending reconnect.
+     */
+    close(): Promise<void>;
+    /**
+     * Opens the SSE connection to the server.
+     *
+     * Idempotent — calling `connect()` when already connected is a no-op.
+     * The SDK's `createSDK` client factory calls this automatically when
+     * `sdk.connect()` is invoked.
+     */
+    connect(): void;
+    private _openEventSource;
+    private _scheduleReconnect;
+    private _clearReconnectTimer;
+}
+//# sourceMappingURL=sse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/transports/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAWpE;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,YAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAChF,OAAO,CAAC,MAAM,CAAQ;IAEtB,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAK;IAC1C,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;IASjD;;;;OAIG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAO/D;;;;OAIG;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;IAK3D;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,gBAAgB;IA8CxB,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,oBAAoB;CAM7B"}