@soulcraft/sdk 1.0.0

package/dist/modules/brainy/errors.js

@@ -0,0 +1,142 @@
+/**
+ * @module modules/brainy/errors
+ * @description Typed error classes for @soulcraft/sdk Brainy operations.
+ *
+ * All errors thrown by SDK transports and handlers extend `SDKError` so callers
+ * can distinguish Soulcraft-specific failures from generic `Error`s with a single
+ * `instanceof` check. Machine-readable `code` fields allow programmatic handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.brainy.find({ query: 'inventory items' })
+ * } catch (err) {
+ *   if (err instanceof SDKTimeoutError) {
+ *     showToast('Connection slow — please retry')
+ *   } else if (err instanceof SDKError) {
+ *     console.error('SDK error:', err.code, err.message)
+ *   } else {
+ *     throw err  // unexpected
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base class for all @soulcraft/sdk errors.
+ *
+ * Carries a machine-readable `code` for programmatic error handling.
+ * All SDK errors extend this class so callers can use a single `instanceof SDKError` check.
+ */
+export class SDKError extends Error {
+    /** Machine-readable error code (e.g. `'DISCONNECTED'`, `'TIMEOUT'`). */
+    code;
+    /**
+     * @param code - Machine-readable identifier.
+     * @param message - Human-readable description.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'SDKError';
+        this.code = code;
+    }
+}
+/**
+ * Thrown when an RPC call is attempted while the transport is not connected.
+ *
+ * Occurs for the HTTP transport when the server is unreachable, or for the
+ * WebSocket transport when the connection is in a disconnected or closed state.
+ */
+export class SDKDisconnectedError extends SDKError {
+    constructor() {
+        super('DISCONNECTED', 'SDK: not connected to a Brainy server');
+        this.name = 'SDKDisconnectedError';
+    }
+}
+/**
+ * Thrown when an RPC call exceeds the configured response timeout.
+ *
+ * The call is cancelled on the client side; the server may still process it.
+ *
+ * @example
+ * ```typescript
+ * if (err instanceof SDKTimeoutError) {
+ *   console.error(`Timed out waiting for: ${err.method}`)
+ * }
+ * ```
+ */
+export class SDKTimeoutError extends SDKError {
+    /** The Brainy method name that timed out (e.g. `'find'`, `'vfs.readdir'`). */
+    method;
+    /**
+     * @param method - Dot-separated Brainy method name that timed out.
+     */
+    constructor(method) {
+        super('TIMEOUT', `SDK: RPC timeout for '${method}' (30s exceeded)`);
+        this.name = 'SDKTimeoutError';
+        this.method = method;
+    }
+}
+/**
+ * Thrown when the server rejects an RPC call due to authentication failure.
+ *
+ * For WebSocket transport: server sends close code 4001 (unauthorized).
+ * For HTTP transport: server responds with HTTP 401.
+ */
+export class SDKAuthError extends SDKError {
+    /**
+     * @param detail - Optional detail appended to the error message.
+     */
+    constructor(detail) {
+        super('UNAUTHORIZED', `SDK: authentication rejected${detail ? ` — ${detail}` : ''}`);
+        this.name = 'SDKAuthError';
+    }
+}
+/**
+ * Thrown when the server rejects an RPC call due to insufficient permissions.
+ *
+ * For WebSocket transport: server sends close code 4003 (forbidden).
+ * For HTTP transport: server responds with HTTP 403.
+ */
+export class SDKForbiddenError extends SDKError {
+    /**
+     * @param detail - Optional detail appended to the error message.
+     */
+    constructor(detail) {
+        super('FORBIDDEN', `SDK: insufficient permissions${detail ? ` — ${detail}` : ''}`);
+        this.name = 'SDKForbiddenError';
+    }
+}
+/**
+ * Thrown when a remote RPC call fails on the server side.
+ *
+ * Wraps the server's error code and message for client-side inspection.
+ */
+export class SDKRpcError extends SDKError {
+    /** The server-side error code returned in the RPC error response. */
+    serverCode;
+    /**
+     * @param serverCode - The error code returned by the server.
+     * @param serverMessage - The human-readable message returned by the server.
+     */
+    constructor(serverCode, serverMessage) {
+        super('RPC_ERROR', `SDK: remote error [${serverCode}] ${serverMessage}`);
+        this.name = 'SDKRpcError';
+        this.serverCode = serverCode;
+    }
+}
+/**
+ * Thrown when a method path cannot be resolved on the target Brainy instance.
+ *
+ * Occurs in the local transport when the dot-separated method string resolves
+ * to a non-existent or non-callable property.
+ */
+export class SDKMethodNotFoundError extends SDKError {
+    /**
+     * @param method - The dot-separated method path that could not be resolved.
+     */
+    constructor(method) {
+        super('METHOD_NOT_FOUND', `SDK: method '${method}' not found on Brainy instance`);
+        this.name = 'SDKMethodNotFoundError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/modules/brainy/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/modules/brainy/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,wEAAwE;IACxD,IAAI,CAAQ;IAE5B;;;OAGG;IACH,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,QAAQ;IAChD;QACE,KAAK,CAAC,cAAc,EAAE,uCAAuC,CAAC,CAAA;QAC9D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,8EAA8E;IAC9D,MAAM,CAAQ;IAE9B;;OAEG;IACH,YAAY,MAAc;QACxB,KAAK,CAAC,SAAS,EAAE,yBAAyB,MAAM,kBAAkB,CAAC,CAAA;QACnE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC;;OAEG;IACH,YAAY,MAAe;QACzB,KAAK,CAAC,cAAc,EAAE,+BAA+B,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACpF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IAC7C;;OAEG;IACH,YAAY,MAAe;QACzB,KAAK,CAAC,WAAW,EAAE,gCAAgC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAClF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,QAAQ;IACvC,qEAAqE;IACrD,UAAU,CAAQ;IAElC;;;OAGG;IACH,YAAY,UAAkB,EAAE,aAAqB;QACnD,KAAK,CAAC,WAAW,EAAE,sBAAsB,UAAU,KAAK,aAAa,EAAE,CAAC,CAAA;QACxE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;IAClD;;OAEG;IACH,YAAY,MAAc;QACxB,KAAK,CAAC,kBAAkB,EAAE,gBAAgB,MAAM,gCAAgC,CAAC,CAAA;QACjF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF"}

package/dist/modules/brainy/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module modules/brainy/events
+ * @description Brainy change event types pushed from a Brainy server to connected clients.
+ *
+ * These events are emitted by the server-side WebSocket handler whenever a write
+ * operation modifies Brainy data. Clients receive them via `onDataChange()` on the
+ * `SoulcraftBrainy` instance, enabling real-time UI updates without polling.
+ *
+ * The WebSocket wire format uses `{ type: 'change', event, entity?, relation? }` so
+ * that the server can multiplex RPC responses and change push events on a single
+ * binary MessagePack stream.
+ */
+/**
+ * An entity snapshot carried inside a {@link BrainyChangeEvent}.
+ *
+ * Contains enough information to update a local cache without a round-trip.
+ */
+export interface BrainyChangeEntity {
+    /** Brainy entity UUID. */
+    id: string;
+    /** NounType string (e.g. `'Thing'`, `'Person'`, `'Document'`). */
+    nounType: string;
+    /** The entity's indexed metadata fields. */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A relation snapshot carried inside a {@link BrainyChangeEvent}.
+ */
+export interface BrainyChangeRelation {
+    /** Source entity UUID. */
+    from: string;
+    /** Target entity UUID. */
+    to: string;
+    /** VerbType string (e.g. `'Contains'`, `'References'`). */
+    verbType: string;
+}
+/**
+ * An unsolicited push event sent from a Brainy server to all connected WebSocket
+ * clients whenever Brainy data is mutated.
+ *
+ * Exactly one of `entity` or `relation` will be populated, depending on whether
+ * the mutation affected an entity or a relationship.
+ *
+ * @example
+ * ```typescript
+ * sdk.brainy.onDataChange((event) => {
+ *   if (event.event === 'add' && event.entity?.nounType === 'InventoryItem') {
+ *     invalidateInventoryCache()
+ *   }
+ * })
+ * ```
+ */
+export interface BrainyChangeEvent {
+    /** Always `'change'` — used to distinguish from RPC responses on the wire. */
+    type: 'change';
+    /** The mutation operation that triggered this event. */
+    event: 'add' | 'update' | 'delete' | 'relate' | 'unrelate';
+    /** Populated for entity mutations (add, update, delete). */
+    entity?: BrainyChangeEntity;
+    /** Populated for relationship mutations (relate, unrelate). */
+    relation?: BrainyChangeRelation;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/modules/brainy/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/modules/brainy/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,IAAI,EAAE,QAAQ,CAAA;IACd,wDAAwD;IACxD,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAA;IAC1D,4DAA4D;IAC5D,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,oBAAoB,CAAA;CAChC"}

package/dist/modules/brainy/events.js

@@ -0,0 +1,14 @@
+/**
+ * @module modules/brainy/events
+ * @description Brainy change event types pushed from a Brainy server to connected clients.
+ *
+ * These events are emitted by the server-side WebSocket handler whenever a write
+ * operation modifies Brainy data. Clients receive them via `onDataChange()` on the
+ * `SoulcraftBrainy` instance, enabling real-time UI updates without polling.
+ *
+ * The WebSocket wire format uses `{ type: 'change', event, entity?, relation? }` so
+ * that the server can multiplex RPC responses and change push events on a single
+ * binary MessagePack stream.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/modules/brainy/events.js.map

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

package/dist/modules/brainy/proxy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module modules/brainy/proxy
+ * @description JavaScript Proxy factory that maps any property access chain into a
+ * transport RPC call.
+ *
+ * Accessing `sdk.brainy.vfs.readdir('/')` never enumerates the Brainy API:
+ * 1. `sdk.brainy.vfs` → new Proxy with namespace `'vfs'`
+ * 2. `.readdir` → new Proxy with namespace `'vfs.readdir'`
+ * 3. Called with `['/']` → dispatches `transport.call('vfs.readdir', ['/'])`
+ *
+ * This means every current and future Brainy method is automatically supported
+ * across all transports without any per-method wiring.
+ *
+ * Special properties handled at the root level without RPC:
+ * - `close()` → `transport.close()`
+ * - `isAlive()` → `transport.isAlive()`
+ * - `onDataChange(h)` → `transport.onEvent(h)`
+ * - `offDataChange(h)` → `transport.offEvent(h)`
+ * - `_transport` → returns the underlying transport (for `connect()` on WS)
+ * - `then` → `undefined` (prevents `await sdk.brainy` from hanging)
+ */
+import type { SDKTransport } from '../../transports/transport.js';
+import type { SoulcraftBrainy } from './types.js';
+/**
+ * Creates a `SoulcraftBrainy` proxy backed by the given transport.
+ *
+ * All property accesses on the returned object are intercepted and accumulated
+ * into a dot-separated method name; when the proxy is invoked as a function
+ * the accumulated name is dispatched to `transport.call()`.
+ *
+ * @param transport - The transport that will handle all RPC dispatches.
+ * @returns A `SoulcraftBrainy` proxy ready for Brainy API calls.
+ *
+ * @example Server-mode (local transport, zero overhead)
+ * ```typescript
+ * const brain = await pool.forUser(userId, workspaceId)
+ * const brainy = createBrainyProxy(new LocalTransport(brain))
+ * const results = await brainy.find({ query: 'candle kits' })
+ * ```
+ *
+ * @example Client-mode (HTTP transport)
+ * ```typescript
+ * const brainy = createBrainyProxy(new HttpTransport(baseUrl, token))
+ * const entity = await brainy.get(entityId)
+ * ```
+ */
+export declare function createBrainyProxy(transport: SDKTransport): SoulcraftBrainy;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/modules/brainy/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../../src/modules/brainy/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,YAAY,GAAG,eAAe,CAE1E"}

package/dist/modules/brainy/proxy.js

@@ -0,0 +1,95 @@
+/**
+ * @module modules/brainy/proxy
+ * @description JavaScript Proxy factory that maps any property access chain into a
+ * transport RPC call.
+ *
+ * Accessing `sdk.brainy.vfs.readdir('/')` never enumerates the Brainy API:
+ * 1. `sdk.brainy.vfs` → new Proxy with namespace `'vfs'`
+ * 2. `.readdir` → new Proxy with namespace `'vfs.readdir'`
+ * 3. Called with `['/']` → dispatches `transport.call('vfs.readdir', ['/'])`
+ *
+ * This means every current and future Brainy method is automatically supported
+ * across all transports without any per-method wiring.
+ *
+ * Special properties handled at the root level without RPC:
+ * - `close()` → `transport.close()`
+ * - `isAlive()` → `transport.isAlive()`
+ * - `onDataChange(h)` → `transport.onEvent(h)`
+ * - `offDataChange(h)` → `transport.offEvent(h)`
+ * - `_transport` → returns the underlying transport (for `connect()` on WS)
+ * - `then` → `undefined` (prevents `await sdk.brainy` from hanging)
+ */
+/**
+ * Creates a `SoulcraftBrainy` proxy backed by the given transport.
+ *
+ * All property accesses on the returned object are intercepted and accumulated
+ * into a dot-separated method name; when the proxy is invoked as a function
+ * the accumulated name is dispatched to `transport.call()`.
+ *
+ * @param transport - The transport that will handle all RPC dispatches.
+ * @returns A `SoulcraftBrainy` proxy ready for Brainy API calls.
+ *
+ * @example Server-mode (local transport, zero overhead)
+ * ```typescript
+ * const brain = await pool.forUser(userId, workspaceId)
+ * const brainy = createBrainyProxy(new LocalTransport(brain))
+ * const results = await brainy.find({ query: 'candle kits' })
+ * ```
+ *
+ * @example Client-mode (HTTP transport)
+ * ```typescript
+ * const brainy = createBrainyProxy(new HttpTransport(baseUrl, token))
+ * const entity = await brainy.get(entityId)
+ * ```
+ */
+export function createBrainyProxy(transport) {
+    return _createProxy(transport, '');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal recursive proxy factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Recursively builds a proxy that accumulates a dot-separated namespace and
+ * dispatches RPC calls when invoked.
+ *
+ * @param transport - The underlying transport instance.
+ * @param namespace - Dot-separated method path accumulated so far (empty at root).
+ * @returns A Proxy that behaves like the Brainy API at this namespace depth.
+ */
+function _createProxy(transport, namespace) {
+    // Use a no-op function as the Proxy target so the Proxy is callable.
+    return new Proxy(function () { }, {
+        get(_target, prop) {
+            // Pass through symbols — avoids breaking spread, iteration, Symbol.toPrimitive, etc.
+            if (typeof prop === 'symbol')
+                return undefined;
+            // Prevent accidental Promise treatment: `await sdk.brainy` must not hang.
+            if (prop === 'then')
+                return undefined;
+            const propStr = String(prop);
+            // Root-level special cases — resolved locally, never sent over the wire.
+            if (namespace === '') {
+                if (propStr === 'close')
+                    return () => transport.close();
+                if (propStr === 'isAlive')
+                    return () => transport.isAlive();
+                if (propStr === 'onDataChange') {
+                    return (h) => transport.onEvent(h);
+                }
+                if (propStr === 'offDataChange') {
+                    return (h) => transport.offEvent(h);
+                }
+                // Expose the underlying transport for callers needing connect() on WsTransport.
+                if (propStr === '_transport')
+                    return transport;
+            }
+            const nextNamespace = namespace ? `${namespace}.${propStr}` : propStr;
+            return _createProxy(transport, nextNamespace);
+        },
+        apply(_target, _thisArg, args) {
+            // The proxy was invoked as a function — dispatch as an RPC call.
+            return transport.call(namespace, args);
+        },
+    });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/modules/brainy/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../../src/modules/brainy/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAuB;IACvD,OAAO,YAAY,CAAC,SAAS,EAAE,EAAE,CAAoB,CAAA;AACvD,CAAC;AAED,gFAAgF;AAChF,mCAAmC;AACnC,gFAAgF;AAEhF;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,SAAuB,EAAE,SAAiB;IAC9D,qEAAqE;IACrE,OAAO,IAAI,KAAK,CAAC,cAAa,CAAC,EAAE;QAC/B,GAAG,CAAC,OAAO,EAAE,IAAqB;YAChC,qFAAqF;YACrF,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAA;YAE9C,0EAA0E;YAC1E,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,SAAS,CAAA;YAErC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;YAE5B,yEAAyE;YACzE,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;gBACrB,IAAI,OAAO,KAAK,OAAO;oBAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;gBACvD,IAAI,OAAO,KAAK,SAAS;oBAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,CAAA;gBAC3D,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;oBAC/B,OAAO,CAAC,CAAiC,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;gBACpE,CAAC;gBACD,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;oBAChC,OAAO,CAAC,CAAiC,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;gBACrE,CAAC;gBACD,gFAAgF;gBAChF,IAAI,OAAO,KAAK,YAAY;oBAAE,OAAO,SAAS,CAAA;YAChD,CAAC;YAED,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;YACrE,OAAO,YAAY,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;QAC/C,CAAC;QAED,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAe;YACtC,iEAAiE;YACjE,OAAO,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QACxC,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/modules/brainy/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module modules/brainy/types
+ * @description Type definitions for `sdk.brainy.*` — the Brainy API proxy surface
+ * exposed by @soulcraft/sdk.
+ *
+ * `SoulcraftBrainy` is a `Pick<Brainy, ...>` over all supported methods, meaning it
+ * stays in sync with whatever version of `@soulcraft/brainy` the consuming project
+ * installs. Adding a method to the Pick list is the only change needed when Brainy
+ * exposes a new API.
+ *
+ * Sub-APIs (`vfs`, `versions`, `neural`, `counts`) are included via their getter
+ * property names so that `sdk.brainy.vfs.readdir('/')` is fully typed — the Proxy
+ * intercepts the property access and routes subsequent calls as `'vfs.readdir'`.
+ *
+ * Additional SDK-specific methods not on Brainy itself:
+ * - `onDataChange` / `offDataChange` — real-time change push subscriptions
+ * - `isAlive` — connection health check
+ * - `close` — graceful disconnect
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { BrainyChangeEvent } from './events.js';
+export type { Entity, Relation, Result, AddParams, UpdateParams, RelateParams, FindParams, BrainyConfig, AggregateDefinition, DiagnosticsResult, } from '@soulcraft/brainy';
+export type { MigrationResult, MigrateOptions, MigrationPreview } from '@soulcraft/brainy';
+export type { NounType, VerbType } from '@soulcraft/brainy';
+export type { BrainyChangeEvent, BrainyChangeEntity, BrainyChangeRelation } from './events.js';
+/**
+ * The public Brainy API surface exposed by @soulcraft/sdk across all four transports.
+ *
+ * Extends `Pick<Brainy, ...>` so TypeScript types are always derived from the
+ * installed `@soulcraft/brainy` version. The runtime implementation is a JavaScript
+ * `Proxy` that maps any method call to `transport.call(methodName, args)`, so
+ * every current and future Brainy method is forwarded without additional per-method code.
+ *
+ * Sub-APIs are accessed via their getter names:
+ * - `brainy.vfs` — Virtual filesystem (`VirtualFileSystem`)
+ * - `brainy.versions` — Entity version history (`VersioningAPI`)
+ * - `brainy.neural()` — Neural extraction and analysis
+ * - `brainy.counts` — Entity and relationship count helpers
+ *
+ * @example
+ * ```typescript
+ * import { createSDK } from '@soulcraft/sdk/server'
+ *
+ * const sdk = createSDK({ mode: 'server', product: 'workshop', ... })
+ *
+ * const results = await sdk.brainy.find({ query: 'candle kits', limit: 10 })
+ * const entity = await sdk.brainy.get(id)
+ * const files = await sdk.brainy.vfs.readdir('/documents')
+ * const versions = await sdk.brainy.versions.list(entityId)
+ * ```
+ */
+export type SoulcraftBrainy = Pick<Brainy, 'add' | 'get' | 'batchGet' | 'update' | 'delete' | 'find' | 'similar' | 'embed' | 'embedBatch' | 'similarity' | 'relate' | 'unrelate' | 'getRelations' | 'neighbors' | 'addMany' | 'deleteMany' | 'updateMany' | 'relateMany' | 'indexStats' | 'findDuplicates' | 'cluster' | 'defineAggregate' | 'removeAggregate' | 'vfs' | 'versions' | 'neural' | 'counts' | 'flush' | 'migrate' | 'diagnostics' | 'clear'> & {
+    /**
+     * Registers a listener for real-time change events pushed from the server.
+     *
+     * No-op for the local transport — in-process mutations are synchronous.
+     * WebSocket and SSE transports dispatch events as they arrive from the server.
+     *
+     * @param handler - Called with each {@link BrainyChangeEvent} as it arrives.
+     */
+    onDataChange(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Removes a previously registered change event listener.
+     *
+     * @param handler - The same function reference passed to `onDataChange`.
+     */
+    offDataChange(handler: (event: BrainyChangeEvent) => void): void;
+    /**
+     * Returns `true` if the client has an active connection to a Brainy instance.
+     *
+     * Always `true` for local and HTTP transports.
+     * Returns `true` only when the WebSocket is in the connected state.
+     */
+    isAlive(): boolean;
+    /**
+     * Gracefully disconnects from the Brainy server and releases resources.
+     *
+     * No-op for local transport (Brainy instance lifecycle is managed by the
+     * server's instance pool). Closes the WebSocket with code 1000 for WS transport.
+     */
+    close(): Promise<void>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/brainy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/brainy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAKpD,YAAY,EACV,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,mBAAmB,CAAA;AAE1B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC1F,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC3D,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,MAAM,EAEJ,KAAK,GACL,KAAK,GACL,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,YAAY,GACZ,YAAY,GAEZ,QAAQ,GACR,UAAU,GACV,cAAc,GACd,WAAW,GAEX,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,YAAY,GAEZ,YAAY,GACZ,gBAAgB,GAChB,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GAEjB,KAAK,GACL,UAAU,GACV,QAAQ,GACR,QAAQ,GAER,OAAO,GACP,SAAS,GACT,aAAa,GACb,OAAO,CACV,GAAG;IACF;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAA;IAE/D;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAA;IAEhE;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAA;IAElB;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA"}

package/dist/modules/brainy/types.js

@@ -0,0 +1,21 @@
+/**
+ * @module modules/brainy/types
+ * @description Type definitions for `sdk.brainy.*` — the Brainy API proxy surface
+ * exposed by @soulcraft/sdk.
+ *
+ * `SoulcraftBrainy` is a `Pick<Brainy, ...>` over all supported methods, meaning it
+ * stays in sync with whatever version of `@soulcraft/brainy` the consuming project
+ * installs. Adding a method to the Pick list is the only change needed when Brainy
+ * exposes a new API.
+ *
+ * Sub-APIs (`vfs`, `versions`, `neural`, `counts`) are included via their getter
+ * property names so that `sdk.brainy.vfs.readdir('/')` is fully typed — the Proxy
+ * intercepts the property access and routes subsequent calls as `'vfs.readdir'`.
+ *
+ * Additional SDK-specific methods not on Brainy itself:
+ * - `onDataChange` / `offDataChange` — real-time change push subscriptions
+ * - `isAlive` — connection health check
+ * - `close` — graceful disconnect
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/modules/brainy/types.js.map

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

package/dist/modules/events/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module modules/events
+ * @description Platform event bus implementation for @soulcraft/sdk.
+ *
+ * Backed by Node's built-in `EventEmitter`. Provides a fully-typed publish/
+ * subscribe interface via {@link EventsModule}. All built-in platform events
+ * (`brainy:change`, `vfs:write`, `vfs:delete`, `vfs:rename`) are emitted
+ * by the SDK itself when the corresponding Brainy or VFS mutations occur.
+ *
+ * Application code and kit integrations can add custom events by extending
+ * the {@link SoulcraftEventMap} interface with declaration merging.
+ *
+ * The returned `EventsModule` instance is bound to a single `EventEmitter`,
+ * so all subscribers on the same SDK instance share a single event stream.
+ * For multi-tenant server deployments, create one SDK instance (and therefore
+ * one event bus) per Brainy scope.
+ */
+import type { EventsModule } from './types.js';
+/**
+ * Creates an `EventsModule` backed by a new Node `EventEmitter`.
+ *
+ * The emitter's default max-listener limit is raised to 100 to support
+ * large numbers of concurrent subscribers in server deployments.
+ *
+ * @returns A typed event bus implementing {@link EventsModule}.
+ *
+ * @example
+ * ```typescript
+ * const events = createEventsModule()
+ *
+ * events.on('vfs:write', ({ path, content }) => {
+ *   console.log('VFS write:', path)
+ * })
+ *
+ * events.emit('vfs:write', { path: '/notes/todo.txt', content: 'Buy candles' })
+ * ```
+ */
+export declare function createEventsModule(): EventsModule;
+export type { EventsModule, SoulcraftEventMap, SoulcraftEventName } from './types.js';
+export type { VfsWriteEvent, VfsDeleteEvent, VfsRenameEvent } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAA;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAuBjD;AAED,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACrF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/modules/events/index.js

@@ -0,0 +1,53 @@
+/**
+ * @module modules/events
+ * @description Platform event bus implementation for @soulcraft/sdk.
+ *
+ * Backed by Node's built-in `EventEmitter`. Provides a fully-typed publish/
+ * subscribe interface via {@link EventsModule}. All built-in platform events
+ * (`brainy:change`, `vfs:write`, `vfs:delete`, `vfs:rename`) are emitted
+ * by the SDK itself when the corresponding Brainy or VFS mutations occur.
+ *
+ * Application code and kit integrations can add custom events by extending
+ * the {@link SoulcraftEventMap} interface with declaration merging.
+ *
+ * The returned `EventsModule` instance is bound to a single `EventEmitter`,
+ * so all subscribers on the same SDK instance share a single event stream.
+ * For multi-tenant server deployments, create one SDK instance (and therefore
+ * one event bus) per Brainy scope.
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Creates an `EventsModule` backed by a new Node `EventEmitter`.
+ *
+ * The emitter's default max-listener limit is raised to 100 to support
+ * large numbers of concurrent subscribers in server deployments.
+ *
+ * @returns A typed event bus implementing {@link EventsModule}.
+ *
+ * @example
+ * ```typescript
+ * const events = createEventsModule()
+ *
+ * events.on('vfs:write', ({ path, content }) => {
+ *   console.log('VFS write:', path)
+ * })
+ *
+ * events.emit('vfs:write', { path: '/notes/todo.txt', content: 'Buy candles' })
+ * ```
+ */
+export function createEventsModule() {
+    const emitter = new EventEmitter();
+    emitter.setMaxListeners(100);
+    return {
+        on(event, handler) {
+            emitter.on(event, handler);
+        },
+        off(event, handler) {
+            emitter.off(event, handler);
+        },
+        emit(event, payload) {
+            emitter.emit(event, payload);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,IAAI,YAAY,EAAE,CAAA;IAClC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAA;IAE5B,OAAO;QACL,EAAE,CACA,KAAQ,EACR,OAAgD;YAEhD,OAAO,CAAC,EAAE,CAAC,KAAe,EAAE,OAAO,CAAC,CAAA;QACtC,CAAC;QAED,GAAG,CACD,KAAQ,EACR,OAAgD;YAEhD,OAAO,CAAC,GAAG,CAAC,KAAe,EAAE,OAAO,CAAC,CAAA;QACvC,CAAC;QAED,IAAI,CAAoC,KAAQ,EAAE,OAA6B;YAC7E,OAAO,CAAC,IAAI,CAAC,KAAe,EAAE,OAAO,CAAC,CAAA;QACxC,CAAC;KACF,CAAA;AACH,CAAC"}