@soulcraft/sdk
The unified Soulcraft platform SDK — data, auth, AI, billing, memory, and
notifications across Workshop, Venue, Academy, Portal, and every kit app.
bun add @soulcraft/sdk
Quick Start
1. Auth — one function for SvelteKit
// hooks.server.ts
import { createSoulcraftAuth } from '@soulcraft/sdk/server'
const auth = createSoulcraftAuth({ product: 'venue' })
export const handle = auth.handle
Mount the route handlers:
// routes/api/auth/logout/+server.ts
export const POST = auth.logoutHandler
// routes/auth/start/+server.ts
export const GET = auth.startHandler
// routes/auth/callback/+server.ts
export const GET = auth.callbackHandler
// routes/auth/session/+server.ts
export const GET = auth.sessionHandler
// routes/api/dev/login/+server.ts
export const GET = auth.devLoginHandler
2. Muse chat endpoint — one function
// routes/api/muse/chat/+server.ts
import { createMuseEndpoint } from '@soulcraft/sdk/server'
export const POST = createMuseEndpoint({
product: 'venue',
tools: myTools,
executeTool: myExecutor,
})
Reads ANTHROPIC_API_KEY, MEMORY_URL, MEMORY_SERVICE_SECRET from env automatically.
3. Service discovery
import { resolveServiceUrl, getServiceSecret } from '@soulcraft/sdk/server'
const memoryUrl = resolveServiceUrl('memory')
// Production: 'https://memory.soulcraft.com'
// Dev: 'http://localhost:5010'
const secret = getServiceSecret()
// Reads SOULCRAFT_SERVICE_SECRET
4. Client proxy (browser)
import { createSoulcraftProxy, HttpRpcTransport } from '@soulcraft/sdk/client'
const sdk = createSoulcraftProxy(new HttpRpcTransport('/api'))
const results = await sdk.brainy.find({ query: 'candle kits' })
const graph = await sdk.graph.getData()
Entry Points
| Import |
Environment |
What |
@soulcraft/sdk |
Any |
Shared types, error classes, format types, namespace contracts |
@soulcraft/sdk/server |
Server only |
Auth, RPC handler, namespace router, service registry, Muse endpoint |
@soulcraft/sdk/client |
Browser only |
Proxy factory, transports (HTTP, WS, PostMessage, SSE), Hall, Y.js |
Environment Variables
| Variable |
Required |
Description |
NODE_ENV |
Production |
Set to production to enable real auth. Dev mode when absent or development. |
SOULCRAFT_SERVICE_SECRET |
Production |
Shared secret for all service-to-service auth. |
ANTHROPIC_API_KEY |
For AI |
Claude API key. |
ORIGIN |
Recommended |
Product's public origin for auth redirects. |
Optional overrides (rarely needed):
| Variable |
Description |
SOULCRAFT_MEMORY_URL |
Override Memory service URL |
SOULCRAFT_FORGE_URL |
Override Forge Kit Registry URL |
SOULCRAFT_ENV |
Force production or development detection |
PORTAL_CREDIT_SECRET |
Portal billing secret (for Muse token billing) |
Exports — @soulcraft/sdk
Shared types safe for any environment. No server dependencies.
Core Types
| Export |
Description |
SoulcraftSDK |
Top-level SDK interface (extends SoulcraftNamespaces) |
SoulcraftNamespaces |
The 25-namespace RPC contract |
SDKOptions, ServerSDKOptions |
Configuration types |
SoulcraftProduct |
Union of registered product names |
Module Types
| Module |
Key Exports |
| Brainy |
Entity, Relation, FindParams, AddParams, UpdateParams, RelateParams, BrainyConfig, NounType, VerbType, BrainyChangeEvent |
| Auth |
SoulcraftSessionUser, SoulcraftSession, PlatformRole |
| AI |
AiModel, AiCompleteOptions, AiStreamEvent, AiTool, AI_MODELS |
| Memory |
RecalledMemory, MemoryNounType, MemoryVerbType, UserProfile, MemoryStats, MemoryGraphData, SynthesisResult, ConversationMessage |
| Hall |
HallRoom, HallRoomHandle, HallPubsubHandle, HallPeerRole, TranscriptEvent, ConceptMentionEvent |
| Billing |
LimitCheckResult, UsageData, SubscriptionData |
| Events |
SoulcraftEventMap, VfsWriteEvent, VfsDeleteEvent |
| Formats |
WvizDocument, WdocDocument, WslideDocument, WquizDocument, SOULCRAFT_FORMATS |
| License |
LicenseResult, LicensePlanTier, AIProviderConfig |
| Kits |
SoulcraftKitConfig, KitsModule |
| Notifications |
Notification, NotificationResult, EmailNotification |
Namespace Interfaces
All 25 namespaces: ChatNamespace, GraphNamespace, SearchNamespace,
CollectionsNamespace, WorkspaceNamespace, SessionNamespace, MediaNamespace,
RealtimeNamespace, CommerceNamespace, CertificationNamespace, FormatsNamespace,
ImagineNamespace, MemoryNamespace, AuthNamespace, PulseNamespace, etc.
Error Classes
SDKError, SDKDisconnectedError, SDKTimeoutError, SDKAuthError,
SDKForbiddenError, SDKReadOnlyError, SDKRpcError, SDKMethodNotFoundError
Exports — @soulcraft/sdk/server
Auth
| Export |
Description |
createSoulcraftAuth(options) |
SvelteKit auth integration — handle hook + all route handlers |
buildLoginUrl(options) |
Build auth.soulcraft.com login redirect URL |
createAuthGateHandle(options) |
Kit-defined auth gate middleware (none/action/entry) |
createRequestAuthMiddleware(verifier) |
Framework-agnostic require/optional auth middleware |
createRemoteSessionVerifier(options) |
Cached IdP session verifier for production |
createDevSessionVerifier(options) |
Synthetic dev session (no OAuth needed) |
createDevCookieVerifier(name?) |
Reads dev login cookie |
createRequestDevLoginHandler(options) |
GET /api/dev/login?role= handler |
createRequestGuestSessionHandler(options) |
Guest session cookie issuer |
getUser(request) |
Retrieve resolved user from request after middleware |
verifyServiceToken(token) |
Verify service-to-service bearer tokens |
computeEmailHash(email) |
SHA-256 of canonical email for Brainy paths |
SOULCRAFT_PRODUCTS |
Product registry — all products, domains, dev ports |
deriveOrigins() |
Trusted origins from product registry |
See docs/AUTH.md for full auth guide.
Muse Endpoint
| Export |
Description |
createMuseEndpoint(options) |
Drop-in Muse chat handler — reads env vars, wires Claude + Memory + billing |
See docs/SERVICES.md for details.
Service Registry
| Export |
Description |
SOULCRAFT_SERVICES |
Registry of all infrastructure services |
resolveServiceUrl(service) |
Resolve URL by name (prod https:// vs dev localhost) |
getServiceSecret() |
Read SOULCRAFT_SERVICE_SECRET |
getServiceHeaders(userEmail) |
Build { 'x-service-secret', 'x-user-email' } headers |
isProduction() |
Detect production vs development environment |
See docs/SERVICES.md for details.
RPC Handler & Router
| Export |
Description |
createRpcHandler(config) |
Framework-agnostic (Request) => Response RPC handler |
createNamespaceRouter(config) |
Core namespace dispatcher |
createNamespaceWsHandler(config) |
WebSocket handler (MessagePack binary) |
createCachedDispatch(config) |
LRU + singleflight RPC response cache |
createReadOnlyAuthorize() |
Read-only enforcement middleware |
Instance Pool
| Export |
Description |
BrainyInstancePool |
Brainy instance pooling — per-user, per-tenant, per-scope |
Module Factories
| Export |
Description |
createBillingModule(options) |
Billing module (Local or Portal provider) |
createLicenseModule(options) |
License/credits module |
createKitsModule() |
Kit loader via Forge Kit Registry |
createNotificationsModule() |
Email (Postmark) + SMS (Twilio) |
createMailClient() |
Mail service client |
Namespace Handler Factories
One factory per namespace. Wire into providers on the router:
createChatHandler, createGraphHandler, createSearchHandler,
createMemoryHandler, createSessionHandler, createWorkspaceHandler,
createBillingHandler, createMediaHandler, createRealtimeHandler,
createCommerceHandler, createImagineHandler, and 11 more.
AI Utilities
streamMessage, sendMessage, analyzeComplexity, selectTieredRouting,
createDefaultModelSelector, estimateCost, formatCost, createAIClientResolver,
DEFAULT_MODELS, DEFAULT_MODEL_TIERS
Exports — @soulcraft/sdk/client
Proxy Factory
| Export |
Description |
createSoulcraftProxy(transport) |
Recursive Proxy — full SoulcraftSDK over any transport |
createVenueProxy(options) |
Venue-specific proxy with service helpers |
Transports
| Export |
Description |
HttpRpcTransport |
JSON POST to /api/rpc — stateless, works everywhere |
PostMessageRpcTransport |
PostMessage — kit iframes in WebContainer |
WsTransport |
MessagePack binary over WebSocket — real-time, bidirectional |
SseTransport |
Server-Sent Events — live updates, VFS/entity changes |
ReadOnlyTransport |
Wrapper that blocks write methods |
Hall (Real-time)
| Export |
Description |
joinHallRoom(options) |
Join a Hall WebRTC room |
joinHallPubsub(options) |
Join a Hall pub/sub channel |
getWhepUrl(roomId) |
WHEP playback URL |
getHlsUrl(roomId) |
HLS stream URL |
Collaborative Editing
| Export |
Description |
createYjsProvider(options) |
Y.js WebSocket provider for collaborative editing |
Detailed Documentation
| Document |
Contents |
| docs/AUTH.md |
Auth module — SvelteKit integration, session verifiers, dev login, auth gate, logout flow |
| docs/MEMORY.md |
Memory types — RecalledMemory, MemoryNounType, UserProfile, graph data, synthesis |
| docs/SERVICES.md |
Service registry, Muse endpoint factory, env var resolution |
| docs/ADR-001-sdk-design.md |
Architecture decision record — why the SDK exists and how it works |
| docs/USAGE.md |
Extended usage guide with examples |
| docs/KIT-APP-GUIDE.md |
Building kit apps with the SDK |
| RELEASES.md |
Version history and migration notes |
Module Namespaces
| Namespace |
Description |
sdk.brainy.* |
Full Brainy API — CRUD, search, embed, cluster, migrate |
sdk.vfs.* |
Virtual filesystem — readFile, writeFile, tree, watch |
sdk.versions.* |
Entity version history — save, list, restore, diff |
sdk.chat.* |
AI chat — conversations, streaming, plans |
sdk.graph.* |
Knowledge graph — nodes, edges, layout |
sdk.search.* |
Unified search — entities, VFS, full-text |
sdk.ai.* |
Claude model tiers, completion, streaming |
sdk.memory.* |
Living AI memory — remember, recall, learn, synthesize |
sdk.events.* |
Platform event bus — VFS, entity, AI activity |
sdk.billing.* |
Usage metering, quota checks, Stripe subscriptions |
sdk.license.* |
Cortex activation, plan/credits/BYOK |
sdk.kits.* |
Kit loader, initialization |
sdk.formats.* |
Soulcraft format types — WVIZ, WDOC, WSLIDE, WQUIZ |
sdk.notifications.* |
Email (Postmark) + SMS (Twilio) |
sdk.hall.* |
Real-time — WebRTC, pub/sub, media, transcription |
sdk.media.* |
Media upload, processing, thumbnails |
sdk.commerce.* |
Products, checkout, payments |
sdk.imagine.* |
Image generation — SDXL, ControlNet |
sdk.realtime.* |
Peer connections, subscriptions |
sdk.session.* |
Session state, API keys, storage |
sdk.workspace.* |
Workspace management |
sdk.collections.* |
View collections |
sdk.annotations.* |
Entity annotations |
sdk.config.* |
Platform configuration |
sdk.pulse.* |
Analytics events |
Publishing
Published to npmjs.com as access:restricted under @soulcraft.
Requires npm login to the @soulcraft org to install.
