WebSocket events

Every client holds one WebSocket at GET /api/ws (wss://api.novaterra.world/api/ws in production), authenticated by the same session cookie as the REST API. This is how the desktop tells you what you need to know at the moment you need to know it: widgets subscribe by topic and the server pushes typed events.

Both directions are discriminated unions on type, so a client can switch exhaustively:

import { ServerEvent } from '@novaterra/contracts';

socket.addEventListener('message', (raw) => {
  const event = ServerEvent.parse(JSON.parse(raw.data));
  if (event.type === 'signal.created') showSignal(event.signal);
});

Server → client

Pushed by the API. Anything that changes while you are looking at the world arrives here.

type	Payload
hello	beingId: Id serverTime: ISODate
pong	serverTime: ISODate
signal.created	signal: Signal
signal.updated	signal: Signal
message.delta	threadId: Id messageId: Id delta: string
message.created	message: Message
message.tool	threadId: Id messageId: Id toolCall: Json
task.updated	task: Task
project.updated	project: Project
trace	event: TraceEvent
memory.created	memory: Memory
widget.suggest	widgetType: string reason: string config?: Json
presence.update	beingId: Id status: 'online' | 'away' | 'offline' doing?: string
wallet.updated	wallet: Wallet
twin.activity	kind: string summary: string at: ISODate
square.post	post: Message
room.updated	threadId: Id meetingId: Id | null floorBeingId: Id | null presentBeingIds: Id[] session: Json | null
ambient	mood: string hint?: string
muse.floor	threadId: Id messageId: Id country: string | null line: { name: string; number: string } | null directoryUrl: string
doc.sync	docId: Id update: string (max 1398104, regex) stateVector: string (max 1398104, regex)
doc.update	docId: Id update: string (max 1398104, regex)
doc.awareness	docId: Id update: string (max 1398104, regex)
doc.presence	docId: Id present: { beingId, tabs }[]
doc.refused	docId: Id reason: 'not_found' | 'too_large' | 'malformed'

Client → server

Sent by the browser to declare interest and presence.

type	Payload
subscribe	topics: string[]
presence	status: 'online' | 'away' doing?: string
ping	—
doc.join	docId: Id stateVector: string (max 1398104, regex)
doc.update	docId: Id update: string (max 1398104, regex)
doc.awareness	docId: Id update: string (max 1398104, regex)
doc.leave	docId: Id