@soulcraft/sdk 1.0.0

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

@@ -0,0 +1,129 @@
+/**
+ * @module modules/events/types
+ * @description Type definitions for `sdk.events.*` — the platform event bus.
+ *
+ * The event bus carries two classes of event:
+ *
+ * **Built-in platform events** — emitted automatically by the SDK when Brainy
+ * or VFS mutations occur:
+ * - `brainy:change`  — any entity or relation mutation in Brainy
+ * - `vfs:write`      — a VFS file was created or updated
+ * - `vfs:delete`     — a VFS file or directory was removed
+ * - `vfs:rename`     — a VFS file or directory was renamed/moved
+ *
+ * **Application events** — arbitrary string keys emitted by product or kit code:
+ * - `kit:session-completed`, `venue:booking-created`, etc.
+ *
+ * All event payloads are typed via the `SoulcraftEventMap` interface. Extend it
+ * with declaration merging in your project to get typed `on()`/`emit()` for
+ * your own events.
+ *
+ * @example Declaring custom events
+ * ```typescript
+ * declare module '@soulcraft/sdk' {
+ *   interface SoulcraftEventMap {
+ *     'kit:session-completed': { userId: string; sessionId: string; kitId: string }
+ *     'venue:booking-created': { bookingId: string; tenantId: string }
+ *   }
+ * }
+ * ```
+ */
+import type { BrainyChangeEvent } from '../brainy/events.js';
+/**
+ * Emitted when a VFS file is created or overwritten.
+ */
+export interface VfsWriteEvent {
+    /** Absolute VFS path, e.g. `/projects/my-project/README.md`. */
+    path: string;
+    /** The file content as a UTF-8 string. */
+    content: string;
+}
+/**
+ * Emitted when a VFS file or directory is deleted.
+ */
+export interface VfsDeleteEvent {
+    /** Absolute VFS path that was removed. */
+    path: string;
+}
+/**
+ * Emitted when a VFS file or directory is renamed or moved.
+ */
+export interface VfsRenameEvent {
+    /** The original path. */
+    from: string;
+    /** The new path. */
+    to: string;
+}
+/**
+ * The canonical map of all platform event names to their payload types.
+ *
+ * Extend this interface in your project with declaration merging to add
+ * type-safe custom events:
+ * ```typescript
+ * declare module '@soulcraft/sdk' {
+ *   interface SoulcraftEventMap {
+ *     'kit:session-completed': { userId: string; sessionId: string; kitId: string }
+ *   }
+ * }
+ * ```
+ */
+export interface SoulcraftEventMap {
+    /** Any entity or relation was mutated in Brainy. */
+    'brainy:change': BrainyChangeEvent;
+    /** A VFS file was created or overwritten. */
+    'vfs:write': VfsWriteEvent;
+    /** A VFS file or directory was removed. */
+    'vfs:delete': VfsDeleteEvent;
+    /** A VFS file or directory was renamed or moved. */
+    'vfs:rename': VfsRenameEvent;
+}
+/** All event names in the platform event map (built-in and custom). */
+export type SoulcraftEventName = keyof SoulcraftEventMap;
+/**
+ * The `sdk.events` namespace.
+ *
+ * Provides a typed publish/subscribe event bus for coordinating platform
+ * events across modules, products, and kit applications.
+ *
+ * @example Subscribing to entity changes
+ * ```typescript
+ * sdk.events.on('brainy:change', (event) => {
+ *   if (event.entity.type === 'Product') {
+ *     updateInventoryCache(event.entity)
+ *   }
+ * })
+ * ```
+ *
+ * @example Emitting a custom application event
+ * ```typescript
+ * await sdk.events.emit('kit:session-completed', {
+ *   userId: user.id,
+ *   sessionId,
+ *   kitId: 'wicks-and-whiskers',
+ * })
+ * ```
+ */
+export interface EventsModule {
+    /**
+     * Subscribe to a platform or application event.
+     *
+     * @param event - The event name to listen for.
+     * @param handler - Called with the event payload each time the event fires.
+     */
+    on<K extends keyof SoulcraftEventMap>(event: K, handler: (payload: SoulcraftEventMap[K]) => void): void;
+    /**
+     * Unsubscribe a previously registered handler.
+     *
+     * @param event - The event name.
+     * @param handler - The same function reference passed to {@link EventsModule.on}.
+     */
+    off<K extends keyof SoulcraftEventMap>(event: K, handler: (payload: SoulcraftEventMap[K]) => void): void;
+    /**
+     * Emit a platform or application event to all registered listeners.
+     *
+     * @param event - The event name.
+     * @param payload - The event payload.
+     */
+    emit<K extends keyof SoulcraftEventMap>(event: K, payload: SoulcraftEventMap[K]): void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/events/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAM5D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;CACX;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,eAAe,EAAE,iBAAiB,CAAA;IAClC,6CAA6C;IAC7C,WAAW,EAAE,aAAa,CAAA;IAC1B,2CAA2C;IAC3C,YAAY,EAAE,cAAc,CAAA;IAC5B,oDAAoD;IACpD,YAAY,EAAE,cAAc,CAAA;CAC7B;AAED,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,MAAM,iBAAiB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAClC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC/C,IAAI,CAAA;IAEP;;;;;OAKG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,iBAAiB,EACnC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC/C,IAAI,CAAA;IAEP;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CACvF"}

package/dist/modules/events/types.js

@@ -0,0 +1,32 @@
+/**
+ * @module modules/events/types
+ * @description Type definitions for `sdk.events.*` — the platform event bus.
+ *
+ * The event bus carries two classes of event:
+ *
+ * **Built-in platform events** — emitted automatically by the SDK when Brainy
+ * or VFS mutations occur:
+ * - `brainy:change`  — any entity or relation mutation in Brainy
+ * - `vfs:write`      — a VFS file was created or updated
+ * - `vfs:delete`     — a VFS file or directory was removed
+ * - `vfs:rename`     — a VFS file or directory was renamed/moved
+ *
+ * **Application events** — arbitrary string keys emitted by product or kit code:
+ * - `kit:session-completed`, `venue:booking-created`, etc.
+ *
+ * All event payloads are typed via the `SoulcraftEventMap` interface. Extend it
+ * with declaration merging in your project to get typed `on()`/`emit()` for
+ * your own events.
+ *
+ * @example Declaring custom events
+ * ```typescript
+ * declare module '@soulcraft/sdk' {
+ *   interface SoulcraftEventMap {
+ *     'kit:session-completed': { userId: string; sessionId: string; kitId: string }
+ *     'venue:booking-created': { bookingId: string; tenantId: string }
+ *   }
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * @module formats/types
+ * @description Type definitions for sdk.formats.*
+ * Implementation: Phase 4 per ADR-001.
+ */
+export type {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}

package/dist/modules/formats/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module formats/types
+ * @description Type definitions for sdk.formats.*
+ * Implementation: Phase 4 per ADR-001.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * @module modules/hall/types
+ * @description Hall module types for @soulcraft/sdk.
+ *
+ * Re-exports the full public API surface of @soulcraft/hall (HallServer, Room, and all
+ * supporting types) so consumers only need to import from @soulcraft/sdk.
+ *
+ * The HallModule interface defines the sdk.hall namespace exposed on SoulcraftSDK.
+ * Hall is server-only — the HallServer runs in-process with the product backend,
+ * and the SDK provides handler factories that products mount as WebSocket routes.
+ *
+ * @see createHallRoomHandler in @soulcraft/sdk/server for the signaling handler.
+ * @see @soulcraft/hall for the NAPI implementation.
+ */
+export type { HallConfig, RoomOptions, RecordingManifest, ConceptEvent, RelationProposedEvent, AttentionEvent, RoomEventMap, } from '@soulcraft/hall';
+export type { Room, HallServer } from '@soulcraft/hall';
+/**
+ * @description The sdk.hall namespace on SoulcraftSDK (server mode only).
+ *
+ * Provides access to the running HallServer instance and room management utilities.
+ * In server mode, the SDK manages one HallServer per process. Products call
+ * createRoom/getRoom directly, then mount the signaling handler returned by
+ * createHallRoomHandler() at their WebSocket route.
+ */
+export interface HallModule {
+    /**
+     * Creates a new room with the given ID and options. Errors if a room with the
+     * same ID already exists — check with getRoom() first.
+     * @param roomId - Unique room identifier (e.g. Brainy session entity ID).
+     * @param options - Room creation options (max peers, transcription, recording, etc.).
+     * @returns The Room instance, ready for peer connections.
+     */
+    createRoom(roomId: string, options: import('@soulcraft/hall').RoomOptions): Promise<import('@soulcraft/hall').Room>;
+    /**
+     * Returns an existing room by ID, or null if it does not exist.
+     * @param roomId - The room ID to look up.
+     * @returns The Room or null.
+     */
+    getRoom(roomId: string): Promise<import('@soulcraft/hall').Room | null>;
+    /**
+     * Close a specific room and disconnect all its peers.
+     * @param roomId - The room ID to close.
+     */
+    closeRoom(roomId: string): Promise<void>;
+    /**
+     * Return IDs of all currently active rooms.
+     * @returns Array of room ID strings.
+     */
+    roomIds(): Promise<string[]>;
+    /**
+     * Shuts down the Hall server and all active rooms, releasing NAPI resources.
+     * Called automatically by sdk.shutdown() in server mode.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,YAAY,EACV,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,iBAAiB,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,iBAAiB,EAAE,IAAI,CAAC,CAAA;IAEnH;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAC,CAAA;IAEvE;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAExC;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAE5B;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB"}

package/dist/modules/hall/types.js

@@ -0,0 +1,16 @@
+/**
+ * @module modules/hall/types
+ * @description Hall module types for @soulcraft/sdk.
+ *
+ * Re-exports the full public API surface of @soulcraft/hall (HallServer, Room, and all
+ * supporting types) so consumers only need to import from @soulcraft/sdk.
+ *
+ * The HallModule interface defines the sdk.hall namespace exposed on SoulcraftSDK.
+ * Hall is server-only — the HallServer runs in-process with the product backend,
+ * and the SDK provides handler factories that products mount as WebSocket routes.
+ *
+ * @see createHallRoomHandler in @soulcraft/sdk/server for the signaling handler.
+ * @see @soulcraft/hall for the NAPI implementation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * @module kits/types
+ * @description Type definitions for sdk.kits.*
+ * Implementation: Phase 4 per ADR-001.
+ */
+export type {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}

package/dist/modules/kits/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module kits/types
+ * @description Type definitions for sdk.kits.*
+ * Implementation: Phase 4 per ADR-001.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * @module license/types
+ * @description Type definitions for sdk.license.*
+ * Implementation: Phase 3 per ADR-001.
+ */
+export type {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/license/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}

package/dist/modules/license/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module license/types
+ * @description Type definitions for sdk.license.*
+ * Implementation: Phase 3 per ADR-001.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * @module notifications/types
+ * @description Type definitions for sdk.notifications.*
+ * Implementation: Phase 5 per ADR-001.
+ */
+export type {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}

package/dist/modules/notifications/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module notifications/types
+ * @description Type definitions for sdk.notifications.*
+ * Implementation: Phase 5 per ADR-001.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,60 @@
+/**
+ * @module modules/skills
+ * @description Skill loading and registry for @soulcraft/sdk.
+ *
+ * Skills are SKILL.md files that define an AI persona, capabilities, and workflow
+ * for a kit domain. This module provides a unified `load()`/`list()`/`install()`
+ * API backed by two sources:
+ *
+ * 1. **VFS** (priority) — `/skills/{kitId}/{skillId}.md` in the Brainy VFS.
+ *    Managed at runtime via `install()` or the kit initialization pipeline.
+ * 2. **Bundled** (fallback) — skills shipped with `@soulcraft/kits`.
+ *    Loaded dynamically via `require` so the kits package is an optional dependency.
+ *
+ * ## VFS path convention
+ * ```
+ * /skills/{kitId}/{skillId}.md
+ * ```
+ * Example: `/skills/wicks-and-whiskers/inventory-health.md`
+ *
+ * ## Bundled fallback
+ *
+ * If `@soulcraft/kits` is installed, `skillRegistry[kitId]` is a Record mapping
+ * skill IDs to their raw SKILL.md content strings. The skills module reads from
+ * this registry when VFS lookup misses. If `@soulcraft/kits` is not installed,
+ * bundled lookup silently returns nothing.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { SkillsModule } from './types.js';
+/**
+ * Options for {@link createSkillsModule}.
+ */
+export interface CreateSkillsModuleOptions {
+    /**
+     * Override the bundled skill registry.
+     *
+     * When provided, this is used instead of the `@soulcraft/kits` package registry.
+     * Primarily used in tests to avoid requiring the kits package to be installed.
+     */
+    bundledRegistry?: Record<string, Record<string, string>> | null;
+}
+/**
+ * Creates a `SkillsModule` backed by a Brainy VFS instance and the bundled
+ * `@soulcraft/kits` skill registry.
+ *
+ * @param brain - An initialized Brainy instance. Required for VFS operations.
+ *   Pass `null` to disable VFS skill loading (bundled registry only).
+ * @param options - Optional configuration including a registry override for tests.
+ * @returns A configured {@link SkillsModule}.
+ *
+ * @example
+ * ```typescript
+ * const brain = await pool.forUser(user.emailHash, workspaceId)
+ * const skills = createSkillsModule(brain)
+ *
+ * const skill = await skills.load('inventory-health', 'wicks-and-whiskers')
+ * ```
+ */
+export declare function createSkillsModule(brain: Brainy | null, options?: CreateSkillsModuleOptions): SkillsModule;
+export type { SkillsModule, Skill, SkillListOptions, SkillInstallOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAgD,MAAM,YAAY,CAAA;AAS5F;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAA;CAChE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAgDd;AAmLD,YAAY,EACV,YAAY,EACZ,KAAK,EACL,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAA"}