@soulcraft/sdk 1.0.0

package/dist/transports/ws.js

@@ -0,0 +1,331 @@
+/**
+ * @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 { encode, decode } from '@msgpack/msgpack';
+import { SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, } from '../modules/brainy/errors.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// WsTransport
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 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 class WsTransport {
+    ws = null;
+    wsUrl;
+    authToken;
+    scope;
+    timeoutMs;
+    maxReconnectAttempts;
+    pending = new Map();
+    nextId = 0;
+    connectionState = 'disconnected';
+    changeListeners = [];
+    connectResolve = null;
+    connectReject = null;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    /**
+     * @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, authToken, scope, timeoutMs = 30_000, maxReconnectAttempts = 10) {
+        this.wsUrl = wsUrl;
+        this.authToken = authToken;
+        this.scope = scope;
+        this.timeoutMs = timeoutMs;
+        this.maxReconnectAttempts = maxReconnectAttempts;
+    }
+    // ── SDKTransport interface ───────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async call(method, args) {
+        if (this.connectionState !== 'connected') {
+            throw new SDKDisconnectedError();
+        }
+        return new Promise((resolve, reject) => {
+            const id = String(this.nextId++);
+            const timeoutId = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new SDKTimeoutError(method));
+            }, this.timeoutMs);
+            this.pending.set(id, { resolve, reject, timeoutId });
+            const request = { id, method, args };
+            this.ws.send(encode(request));
+        });
+    }
+    /**
+     * Registers a listener for real-time change push events 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 WsTransport.onEvent}.
+     */
+    offEvent(handler) {
+        const idx = this.changeListeners.indexOf(handler);
+        if (idx !== -1)
+            this.changeListeners.splice(idx, 1);
+    }
+    /**
+     * Returns `true` when the WebSocket is in the connected state.
+     */
+    isAlive() {
+        return this.connectionState === 'connected';
+    }
+    /**
+     * Closes the WebSocket connection permanently.
+     *
+     * After `close()`, this transport instance cannot be reconnected.
+     * All pending RPC calls are rejected with {@link SDKDisconnectedError}.
+     */
+    async close() {
+        this.connectionState = 'closed';
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this._rejectAllPending(new SDKDisconnectedError());
+        if (this.ws) {
+            this.ws.close(1000, 'Client disconnect');
+            this.ws = null;
+        }
+    }
+    // ── Connection management ────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async connect() {
+        if (this.connectionState === 'connected')
+            return;
+        if (this.connectionState === 'closed') {
+            throw new Error('WsTransport: cannot reconnect after explicit close()');
+        }
+        this.connectionState = 'connecting';
+        return new Promise((resolve, reject) => {
+            const readyTimeout = setTimeout(() => {
+                if (this.connectionState !== 'connected') {
+                    reject(new Error(`WsTransport: timed out waiting for 'ready' from ${this.wsUrl}`));
+                }
+            }, 15_000);
+            this.connectResolve = () => {
+                clearTimeout(readyTimeout);
+                resolve();
+            };
+            this.connectReject = (e) => {
+                clearTimeout(readyTimeout);
+                reject(e);
+            };
+            this._openSocket();
+        });
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    _openSocket() {
+        const url = this.scope
+            ? `${this.wsUrl}?scope=${encodeURIComponent(this.scope)}`
+            : this.wsUrl;
+        // Bun supports custom headers on WebSocket upgrade (non-standard extension).
+        // @ts-expect-error — Bun-specific WebSocket constructor options
+        this.ws = new WebSocket(url, { headers: { Authorization: `Bearer ${this.authToken}` } });
+        this.ws.binaryType = 'arraybuffer';
+        this.ws.onopen = () => {
+            // Connection established; waiting for server 'ready' message.
+        };
+        this.ws.onmessage = (event) => {
+            this._handleMessage(event.data);
+        };
+        this.ws.onerror = (event) => {
+            console.error('[SDK/ws] WebSocket error', event);
+        };
+        this.ws.onclose = (event) => {
+            this._handleClose(event.code, event.reason);
+        };
+    }
+    _handleMessage(data) {
+        let msg;
+        try {
+            msg = decode(new Uint8Array(data));
+        }
+        catch (err) {
+            console.error('[SDK/ws] Failed to decode MessagePack message', err);
+            return;
+        }
+        if (!msg || typeof msg !== 'object')
+            return;
+        const m = msg;
+        // Ready handshake
+        if (m['type'] === 'ready') {
+            const ready = m;
+            this.connectionState = 'connected';
+            this.reconnectAttempts = 0;
+            console.log(`[SDK/ws] Ready — scope: ${ready.scope}`);
+            this.connectResolve?.();
+            this.connectResolve = null;
+            this.connectReject = null;
+            return;
+        }
+        // RPC response (has an 'id' field)
+        if (typeof m['id'] === 'string') {
+            const response = m;
+            const pending = this.pending.get(response.id);
+            if (!pending)
+                return; // Response to timed-out or unknown request
+            clearTimeout(pending.timeoutId);
+            this.pending.delete(response.id);
+            if (response.error) {
+                pending.reject(new SDKRpcError(response.error.code, response.error.message));
+            }
+            else {
+                pending.resolve(response.result);
+            }
+            return;
+        }
+        // Change push event
+        if (m['type'] === 'change') {
+            const event = m;
+            for (const listener of this.changeListeners) {
+                try {
+                    listener(event);
+                }
+                catch (err) {
+                    console.error('[SDK/ws] Change listener threw', err);
+                }
+            }
+        }
+    }
+    _handleClose(code, reason) {
+        const wasConnecting = this.connectionState === 'connecting';
+        // Auth failures: never retry
+        if (code === 4001) {
+            this.connectionState = 'closed';
+            const err = new SDKAuthError('WebSocket close 4001');
+            this._rejectAllPending(err);
+            this.connectReject?.(err);
+            this.connectResolve = this.connectReject = null;
+            return;
+        }
+        if (code === 4003) {
+            this.connectionState = 'closed';
+            const err = new SDKForbiddenError('WebSocket close 4003');
+            this._rejectAllPending(err);
+            this.connectReject?.(err);
+            this.connectResolve = this.connectReject = null;
+            return;
+        }
+        // Explicit disconnect
+        if (this.connectionState === 'closed') {
+            this._rejectAllPending(new SDKDisconnectedError());
+            return;
+        }
+        // Unexpected disconnect while connecting
+        if (wasConnecting) {
+            this.connectionState = 'disconnected';
+            const err = new Error(`WsTransport: closed during connect (code=${code}, reason=${reason})`);
+            this._rejectAllPending(err);
+            this.connectReject?.(err);
+            this.connectResolve = this.connectReject = null;
+            return;
+        }
+        // Unexpected disconnect while connected → attempt reconnect
+        this.connectionState = 'disconnected';
+        this._rejectAllPending(new SDKDisconnectedError());
+        if (this.reconnectAttempts < this.maxReconnectAttempts) {
+            const backoffMs = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30_000);
+            this.reconnectAttempts++;
+            console.log(`[SDK/ws] Reconnecting in ${backoffMs}ms ` +
+                `(attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.connectionState = 'connecting';
+                this._openSocket();
+            }, backoffMs);
+        }
+        else {
+            console.error(`[SDK/ws] Max reconnect attempts reached for ${this.wsUrl}`);
+            this.connectionState = 'closed';
+        }
+    }
+    _rejectAllPending(error) {
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timeoutId);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=ws.js.map

package/dist/transports/ws.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @module types
+ * @description Core shared types for @soulcraft/sdk. Defines the top-level SoulcraftSDK
+ * interface and configuration options for both server and client modes. All module
+ * namespaces (brainy, vfs, auth, etc.) hang off of SoulcraftSDK.
+ */
+/** Products that can register as OIDC clients of auth.soulcraft.com. */
+export type SoulcraftProduct = 'workshop' | 'venue' | 'academy' | 'portal';
+/** Brainy instance pooling strategies. */
+export type InstanceStrategy = 'per-user' | 'per-tenant' | 'per-scope';
+/** Transport protocols supported by the client SDK. */
+export type Transport = 'http' | 'ws' | 'sse' | 'local';
+/**
+ * @description The top-level SDK interface. Every module namespace is accessible
+ * as a property. Server mode additionally exposes shutdown() and flush().
+ * Client mode exposes connect() for WebSocket transports.
+ */
+export interface SoulcraftSDK {
+    /** Full Brainy graph API — CRUD, search, embed, cluster, migrate, neural, counts. */
+    readonly brainy: BrainyModule;
+    /** Virtual filesystem — readFile, writeFile, tree, watch, search, stat, rename. */
+    readonly vfs: VfsModule;
+    /** Entity version history — save, list, restore, compare, diff. */
+    readonly versions: VersionsModule;
+    /** Auth — OIDC session, capability tokens, middleware factories. */
+    readonly auth: AuthModule;
+    /** Licensing — Cortex activation, plan info, AI credits, BYOK. */
+    readonly license: LicenseModule;
+    /** AI — Claude model tiers, delegator, Briggy companion API, tool definitions. */
+    readonly ai: AiModule;
+    /** Platform event bus — emit and subscribe to VFS, entity, and AI activity events. */
+    readonly events: EventsModule;
+    /** Skill system — load, install, and query VFS-backed and bundled skills. */
+    readonly skills: SkillsModule;
+    /** Kit system — load kits, initialize workspaces from kit templates. */
+    readonly kits: KitsModule;
+    /** Soulcraft format types — WvizDocument, WDOC, WSLIDE, WQUIZ schemas. */
+    readonly formats: FormatsModule;
+    /** Usage metering, quota checks, top-up credits, Stripe subscriptions. */
+    readonly billing: BillingModule;
+    /** Email (Postmark) + SMS (Twilio) + dev-mode console notifications. */
+    readonly notifications: NotificationsModule;
+    /**
+     * Real-time communication — WebRTC SFU, chat, data channels, transcription, recording.
+     * Present only when @soulcraft/hall is installed and configured in ServerSDKOptions.hall.
+     */
+    readonly hall?: HallModule;
+    /** Server-mode only: gracefully flush all Brainy instances and release resources. */
+    shutdown?(): Promise<void>;
+    /** Server-mode only: flush a specific user/tenant's Brainy instance to storage. */
+    flush?(scopeKey: string): Promise<void>;
+    /** Client-mode only: connect the WebSocket transport. */
+    connect?(): Promise<void>;
+    /** Client-mode only: disconnect and clean up. */
+    disconnect?(): Promise<void>;
+}
+import type { SoulcraftBrainy } from './modules/brainy/types.js';
+import type { VfsModule as _VfsModule } from './modules/vfs/types.js';
+import type { VersionsModule as _VersionsModule } from './modules/versions/types.js';
+import type { HallModule as _HallModule } from './modules/hall/types.js';
+import type { AuthModule as _AuthModule } from './modules/auth/types.js';
+import type { AiModule as _AiModule } from './modules/ai/types.js';
+import type { EventsModule as _EventsModule } from './modules/events/types.js';
+import type { SkillsModule as _SkillsModule } from './modules/skills/types.js';
+export type BrainyModule = SoulcraftBrainy;
+export type VfsModule = _VfsModule;
+export type VersionsModule = _VersionsModule;
+export type HallModule = _HallModule;
+export type AuthModule = _AuthModule;
+export type AiModule = _AiModule;
+export type EventsModule = _EventsModule;
+export type SkillsModule = _SkillsModule;
+export type LicenseModule = Record<string, unknown>;
+export type KitsModule = Record<string, unknown>;
+export type FormatsModule = Record<string, unknown>;
+export type BillingModule = Record<string, unknown>;
+export type NotificationsModule = Record<string, unknown>;
+/**
+ * @description Base options shared by both server and client SDK modes.
+ */
+export interface SDKOptions {
+    /** Which Soulcraft product is this SDK instance for. */
+    product: SoulcraftProduct;
+}
+/**
+ * @description Options for server mode — creates and manages Brainy instances directly.
+ * Use `@soulcraft/sdk/server` entry point.
+ */
+export interface ServerSDKOptions extends SDKOptions {
+    mode: 'server';
+    brainy: {
+        storage: 'filesystem' | 'mmap-filesystem';
+        dataPath: string;
+        instances: {
+            strategy: InstanceStrategy;
+            /** For per-scope: custom key function called with (userId, workspaceId). */
+            scopeKey?: (userId: string, workspaceId: string) => string;
+            maxInstances?: number;
+            flushOnEvict?: boolean;
+        };
+    };
+    auth: {
+        clientId: string;
+        clientSecret: string;
+        sessionCacheTtlMs?: number;
+        sessionCacheMax?: number;
+    };
+    license: {
+        /** Path to .soulcraft.json file. Defaults to ./.soulcraft.json. */
+        activationFile?: string;
+        portalUrl?: string;
+    };
+    /**
+     * Optional Hall real-time communication configuration.
+     * When present, the SDK initializes a HallServer and exposes it as sdk.hall.
+     * Requires @soulcraft/hall to be installed.
+     */
+    hall?: {
+        /** Public IP address announced in WebRTC ICE candidates. Required in production. */
+        publicIp: string;
+        /** UDP port range start for ICE candidates (default: 40000). */
+        portMin?: number;
+        /** UDP port range end for ICE candidates (default: 49999). */
+        portMax?: number;
+        /** TURN server URL, e.g. "turn:hall.soulcraft.com:3478". */
+        turnUrl?: string;
+        /** TURN credentials username (static; use generateTurnCredentials for per-peer creds). */
+        turnUsername?: string;
+        /** TURN credentials password (static). */
+        turnPassword?: string;
+        /** S3 bucket name for recording uploads. */
+        recordingBucket?: string;
+        /** Deepgram API key for real-time transcription. */
+        deepgramApiKey?: string;
+    };
+}
+/**
+ * @description Options for client mode — connects to a running SDK server over a transport.
+ * Use `@soulcraft/sdk/client` entry point.
+ */
+export interface ClientSDKOptions extends SDKOptions {
+    mode: 'client';
+    transport: 'http' | 'ws' | 'sse';
+    baseUrl: string;
+    /** Auth strategy: session cookies (same-origin) or a Bearer capability token. */
+    auth?: 'cookie' | {
+        token: string;
+    };
+    /** Request timeout in ms. Defaults to 30 000. */
+    timeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * @module types
+ * @description Core shared types for @soulcraft/sdk. Defines the top-level SoulcraftSDK
+ * interface and configuration options for both server and client modes. All module
+ * namespaces (brainy, vfs, auth, etc.) hang off of SoulcraftSDK.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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