@soulcraft/sdk 1.0.0

package/dist/transports/sse.js

@@ -0,0 +1,192 @@
+/**
+ * @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 { SDKError } from '../modules/brainy/errors.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 class SseTransport {
+    eventsUrl;
+    workspaceId;
+    eventSource = null;
+    changeListeners = [];
+    closed = false;
+    reconnectAttempts = 0;
+    maxReconnectAttempts = 10;
+    reconnectTimer = null;
+    /**
+     * @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, workspaceId) {
+        const base = baseUrl.replace(/\/$/, '');
+        const params = workspaceId ? `?workspaceId=${encodeURIComponent(workspaceId)}` : '';
+        this.eventsUrl = `${base}/api/workspace/events${params}`;
+        this.workspaceId = workspaceId;
+    }
+    // ── SDKTransport interface ───────────────────────────────────────────────
+    /**
+     * Not supported — SSE is a server-push-only transport.
+     *
+     * @throws {@link SDKError} always.
+     */
+    async call(_method, _args) {
+        throw new SDKError('SSE_NO_RPC', 'SDK/sse: SSE transport does not support RPC calls. Use HttpTransport for outbound operations.');
+    }
+    /**
+     * Registers a listener for real-time change events received from the server.
+     *
+     * @param handler - Called with each {@link BrainyChangeEvent} as it arrives.
+     */
+    onEvent(handler) {
+        this.changeListeners.push(handler);
+    }
+    /**
+     * Removes a previously registered change event listener.
+     *
+     * @param handler - The same function reference passed to {@link SseTransport.onEvent}.
+     */
+    offEvent(handler) {
+        const idx = this.changeListeners.indexOf(handler);
+        if (idx !== -1)
+            this.changeListeners.splice(idx, 1);
+    }
+    /**
+     * Returns `true` when the `EventSource` is in the `OPEN` state.
+     */
+    isAlive() {
+        return this.eventSource?.readyState === EventSource.OPEN;
+    }
+    /**
+     * Permanently closes the SSE connection and cancels any pending reconnect.
+     */
+    async close() {
+        this.closed = true;
+        this._clearReconnectTimer();
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+    }
+    // ── Connection management ────────────────────────────────────────────────
+    /**
+     * 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() {
+        if (this.closed) {
+            throw new Error('SseTransport: cannot reconnect after close()');
+        }
+        if (this.eventSource)
+            return;
+        this._openEventSource();
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    _openEventSource() {
+        if (this.closed)
+            return;
+        try {
+            this.eventSource = new EventSource(this.eventsUrl);
+            this.eventSource.onopen = () => {
+                this.reconnectAttempts = 0;
+            };
+            this.eventSource.onmessage = (event) => {
+                if (!event.data || event.data.trim().startsWith(':'))
+                    return;
+                let data;
+                try {
+                    data = JSON.parse(event.data);
+                }
+                catch {
+                    return;
+                }
+                if (data.type === 'connected')
+                    return; // Internal handshake — no listener notify
+                if (data.type === 'change') {
+                    const changeEvent = data;
+                    for (const listener of this.changeListeners) {
+                        try {
+                            listener(changeEvent);
+                        }
+                        catch (err) {
+                            console.error('[SDK/sse] Change listener threw', err);
+                        }
+                    }
+                }
+            };
+            this.eventSource.onerror = () => {
+                if (this.closed)
+                    return;
+                this.eventSource?.close();
+                this.eventSource = null;
+                this._scheduleReconnect();
+            };
+        }
+        catch (err) {
+            console.error('[SDK/sse] Failed to create EventSource', err);
+            this._scheduleReconnect();
+        }
+    }
+    _scheduleReconnect() {
+        if (this.closed || this.reconnectAttempts >= this.maxReconnectAttempts) {
+            if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+                console.error(`[SDK/sse] Max reconnect attempts reached for ${this.eventsUrl}`);
+            }
+            return;
+        }
+        const backoffMs = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30_000);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this._openEventSource();
+        }, backoffMs);
+    }
+    _clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/transports/sse.js.map

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

package/dist/transports/transport.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module transports/transport
+ * @description Transport interface contract for @soulcraft/sdk.
+ *
+ * All four transports (local, HTTP, WebSocket, SSE) implement this interface.
+ * The `sdk.brainy` Proxy wraps the chosen transport and maps any property access
+ * chain + function call into a `transport.call()` dispatch, so a consumer calling
+ * `sdk.brainy.vfs.readdir('/')` triggers `transport.call('vfs.readdir', ['/'])`.
+ *
+ * The SSE transport is receive-only (no `call()` — it throws if called) and is
+ * used alongside the HTTP transport to receive live VFS and entity change events.
+ */
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+/**
+ * Contract that every SDK transport must fulfil.
+ *
+ * Implementations are responsible for:
+ * - Serializing method names and arguments to the wire format
+ * - Deserializing results or errors from the server
+ * - Maintaining connection state (WebSocket transport)
+ * - Emitting change events (WebSocket and SSE transports; no-op for others)
+ */
+export interface SDKTransport {
+    /**
+     * Dispatch an RPC call for the given Brainy method.
+     *
+     * @param method - Dot-separated Brainy method name (e.g. `'vfs.readdir'`, `'find'`).
+     * @param args - Positional arguments to forward to the Brainy method.
+     * @returns A Promise resolving to whatever the Brainy method returns.
+     * @throws {@link SDKDisconnectedError} if not connected.
+     * @throws {@link SDKTimeoutError} if the call exceeds the timeout.
+     * @throws {@link SDKRpcError} if the server returns an error response.
+     */
+    call(method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Register a listener for real-time change events.
+     *
+     * For transports that do not support push (HTTP, local), this is a no-op.
+     * WebSocket and SSE transports dispatch events as they arrive.
+     *
+     * @param handler - Called with each {@link BrainyChangeEvent}.
+     */
+    onEvent(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Remove a previously registered change event listener.
+     *
+     * @param handler - The same function reference passed to {@link SDKTransport.onEvent}.
+     */
+    offEvent(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Returns `true` if the transport has an active, usable connection.
+     *
+     * Local transport always returns `true`.
+     * HTTP transport always returns `true` (errors surface per-call).
+     * WebSocket transport returns `true` only when connected.
+     * SSE transport returns `true` when the EventSource is open.
+     */
+    isAlive(): boolean;
+    /**
+     * Gracefully shut down this transport, releasing any open connections.
+     *
+     * Local and HTTP transports are no-ops.
+     * WebSocket closes with code 1000.
+     * SSE closes the EventSource.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAA;IAE1D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAA;IAE3D;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAA;IAElB;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB"}

package/dist/transports/transport.js

@@ -0,0 +1,14 @@
+/**
+ * @module transports/transport
+ * @description Transport interface contract for @soulcraft/sdk.
+ *
+ * All four transports (local, HTTP, WebSocket, SSE) implement this interface.
+ * The `sdk.brainy` Proxy wraps the chosen transport and maps any property access
+ * chain + function call into a `transport.call()` dispatch, so a consumer calling
+ * `sdk.brainy.vfs.readdir('/')` triggers `transport.call('vfs.readdir', ['/'])`.
+ *
+ * The SSE transport is receive-only (no `call()` — it throws if called) and is
+ * used alongside the HTTP transport to receive live VFS and entity change events.
+ */
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transports/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/transports/ws.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @module transports/ws
+ * @description WebSocket transport — bidirectional MessagePack RPC with push change events.
+ *
+ * ## Wire protocol
+ *
+ * **Client → Server** (binary MessagePack):
+ * ```
+ * { id: string, method: string, args: unknown[] }
+ * ```
+ *
+ * **Server → Client** (binary MessagePack), three message kinds:
+ * 1. Ready handshake: `{ type: 'ready', scope: string }`
+ * 2. RPC response:    `{ id: string, result?: unknown, error?: { code, message } }`
+ * 3. Change push:     `{ type: 'change', event: 'add'|'update'|'delete'|'relate'|'unrelate', entity?, relation? }`
+ *
+ * ## Auth
+ *
+ * The capability token is sent as `Authorization: Bearer <token>` on the WebSocket
+ * upgrade request (Bun-specific header injection). The optional `scope` parameter
+ * is passed as a query string so Venue can select the correct tenant brain.
+ *
+ * ## Reconnection
+ *
+ * On unexpected disconnection the transport automatically retries with exponential
+ * backoff (1 s → 30 s cap) up to `maxReconnectAttempts` times.
+ * Auth failures (close codes 4001, 4003) do not retry.
+ *
+ * @example
+ * ```typescript
+ * import { createSDK } from '@soulcraft/sdk/client'
+ *
+ * const sdk = createSDK({
+ *   mode: 'client',
+ *   product: 'workshop',
+ *   transport: 'ws',
+ *   baseUrl: 'wss://venue.soulcraft.com',
+ *   auth: { token: capabilityToken },
+ * })
+ *
+ * await sdk.connect()
+ *
+ * sdk.brainy.onDataChange((event) => {
+ *   console.log('Remote change:', event.event, event.entity?.nounType)
+ * })
+ *
+ * const results = await sdk.brainy.find({ query: 'inventory' })
+ * ```
+ */
+import type { SDKTransport } from './transport.js';
+import type { BrainyChangeEvent } from '../modules/brainy/events.js';
+/**
+ * Transport that communicates via MessagePack-encoded WebSocket RPC.
+ *
+ * Supports both outbound RPC calls and inbound change push events from the
+ * server. Auto-reconnects on unexpected disconnection.
+ *
+ * Call `connect()` once before making any `call()` invocations. The SDK's
+ * `createSDK` client factory calls this automatically when `sdk.connect()` is
+ * invoked.
+ */
+export declare class WsTransport implements SDKTransport {
+    private ws;
+    private readonly wsUrl;
+    private readonly authToken;
+    private readonly scope;
+    private readonly timeoutMs;
+    private readonly maxReconnectAttempts;
+    private readonly pending;
+    private nextId;
+    private connectionState;
+    private readonly changeListeners;
+    private connectResolve;
+    private connectReject;
+    private reconnectAttempts;
+    private reconnectTimer;
+    /**
+     * @param wsUrl - WebSocket endpoint URL, e.g. `'wss://venue.soulcraft.com/api/brainy/ws'`.
+     * @param authToken - HMAC-signed capability token from `createCapabilityToken()`.
+     * @param scope - Optional scope (tenant slug) passed as `?scope=` on connect.
+     * @param timeoutMs - RPC call timeout in milliseconds. Default: 30 000.
+     * @param maxReconnectAttempts - Max reconnect attempts on unexpected disconnect. Default: 10.
+     */
+    constructor(wsUrl: string, authToken: string, scope?: string, timeoutMs?: number, maxReconnectAttempts?: number);
+    /**
+     * Sends a MessagePack-encoded RPC request and awaits the response.
+     *
+     * @param method - Dot-separated Brainy method name (e.g. `'vfs.readdir'`).
+     * @param args - Positional arguments to forward.
+     * @returns Whatever the server's Brainy method returns.
+     * @throws {@link SDKDisconnectedError} if not connected.
+     * @throws {@link SDKTimeoutError} after `timeoutMs` ms.
+     * @throws {@link SDKRpcError} if the server reports an error.
+     */
+    call(method: string, args: unknown[]): Promise<unknown>;
+    /**
+     * Registers a listener for real-time change push events 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 WsTransport.onEvent}.
+     */
+    offEvent(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Returns `true` when the WebSocket is in the connected state.
+     */
+    isAlive(): boolean;
+    /**
+     * Closes the WebSocket connection permanently.
+     *
+     * After `close()`, this transport instance cannot be reconnected.
+     * All pending RPC calls are rejected with {@link SDKDisconnectedError}.
+     */
+    close(): Promise<void>;
+    /**
+     * Establishes the WebSocket connection and waits for the server `ready` message.
+     *
+     * Must be called once before any `call()` invocations. Resolves when the server
+     * confirms successful authentication and scope selection. The SDK's `createSDK`
+     * client factory exposes this as `sdk.connect()`.
+     *
+     * @throws Error if authentication fails (close codes 4001 / 4003).
+     * @throws Error if no `ready` message arrives within 15 seconds.
+     */
+    connect(): Promise<void>;
+    private _openSocket;
+    private _handleMessage;
+    private _handleClose;
+    private _rejectAllPending;
+}
+//# sourceMappingURL=ws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transports/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAkDpE;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAE7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAI;IAElB,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAEhF,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,aAAa,CAAoC;IAEzD,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;;;;OAMG;gBAED,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,SAAS,EAClB,oBAAoB,SAAK;IAW3B;;;;;;;;;OASG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB7D;;;;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;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B9B,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,iBAAiB;CAO1B"}