@mistscale/web-sdk

TypeScript-first browser SDK for MistScale: list a project's NPCs and hold realtime chat/voice/spatial-context conversations with them over WebSocket.

Targets browser games, interactive fiction, chat-based games, and chatbot-style demos — anything that can run JavaScript in a browser (or any WebSocket/fetch-capable JS runtime; nothing here is browser-DOM-specific beyond WebSocket, fetch, and crypto.randomUUID).

Install

npm install @mistscale/web-sdk

Quick start

import { MistScale } from '@mistscale/web-sdk';

const mistscale = new MistScale({ apiKey: 'ms_...' }); // Project Settings → API Keys

const npcs = await mistscale.npcs.list();
const connection = mistscale.connect(npcs[0].id);

connection.on('chatChunk', (e) => process.stdout.write(e.delta));   // streamed tokens
connection.on('chatMessage', (e) => console.log('\n[final]', e.text)); // settled turn

connection.on('open', () => connection.sendChat('Hello there!'));

Public API

new MistScale(config)

interface MistScaleConfig {
  apiKey: string;              // required, must start with "ms_"
  controlPlaneUrl?: string;    // default: https://api.mistscale.com
  npcServiceUrl?: string;      // default: https://npc.mistscale.com (auto-upgraded to wss://)
  playerId?: string;           // default sender/player id for every connection; auto-generated if omitted
  requestTimeoutMs?: number;   // default: 15000, REST calls only
}

Throws MistScaleConfigError synchronously if apiKey is missing or malformed — no network call happens at construction time.

mistscale.npcs

• list(): Promise<NPCSummary[]> — GET /v1/npcs, every NPC in the key's project.
• verifyKey(): Promise<boolean> — POST /v1/auth/verify-key.

mistscale.connect(npcId, options?): NPCConnection

Opens one WebSocket to one NPC.

interface ConnectOptions {
  playerId?: string;            // overrides MistScaleConfig.playerId for this connection
  instanceId?: string;          // auto-generated UUID if omitted
  autoReconnect?: boolean;      // default true
  maxReconnectDelayMs?: number; // default 30000
}

NPCConnection

Methods:

• sendChat(message: string, senderId?: string): void
• sendVoiceChunk(data: ArrayBuffer | Uint8Array, end?: boolean, senderId?: string): void
• setSpatialContext(location: string, opts?: { timeOfDay?: string; weather?: string }): void
• getEvolutionStatus(): void / getQuotaStatus(): void
• close(): void
• .state: 'connecting' | 'open' | 'closing' | 'closed'

Events (connection.on(event, handler) => unsubscribe):

| Event | Payload | When | |---|---|---| | open | — | socket connected | | close | {code, reason, expected} | socket closed (expected is true for client-initiated closes) | | error | Error | transport-level error | | chatChunk | {chatId, delta} | one streamed token — append | | chatRevision | {chatId, text} | grounding rewrote the reply — replace | | chatMessage | {chatId, text, finalizedByMetadata, metadata?} | turn settled | | transcript | {text} | voice message transcribed | | chatBlocked | {chatType, reason, limit, used} | quota exceeded, no reply generated | | quotaStatus | {text, voice} | reply to getQuotaStatus() | | evolutionStatus | metadata object | reply to getEvolutionStatus() | | audio | ArrayBuffer | synthesized speech (voice replies only) | | reconnecting | {attempt, delayMs} | auto-reconnect about to fire |

Streaming contract: append chatChunk.delta to build the visible text; if chatRevision arrives, replace the accumulated text outright; chatMessage is the settled final state for the turn. See docs/websocket-api.md for the full server-side rationale (this mirrors the buffering the production Unity SDK and dashboard client already do).

Errors

MistScaleError (base) → MistScaleConfigError, MistScaleAPIError → MistScaleAuthError / MistScaleRateLimitError, MistScaleTimeoutError, MistScaleConnectionError. See src/errors.ts.

What this SDK does not do

NPC authoring (create/update/delete), knowledge/RAG upload, behaviour rules, NPC-to-NPC relationships, and the Playground session API are studio/dashboard operations gated behind a dashboard session, not a project API key — they are out of scope for a game client and therefore out of scope for this SDK. See docs/rest-api.md, "Endpoints out of scope for the SDK".

Raw API docs

If you'd rather not install the SDK: docs/rest-api.md and docs/websocket-api.md document the exact same contract this package implements.

Development

npm install
npm run build       # tsup -> dist/ (ESM + CJS + .d.ts)
npm run typecheck
npm test

See examples/vanilla-chat for a working browser example.