SDK reference · RMC Docs

Import the shared client and types from @rmc/client. This reference describes the public client methods at the code revision linked in the footer.

Client and room ownership

Method	Result	Notes
`new RmcClient(baseUrl, options?)`	`RmcClient`	Optional `fetch` and `webSocket` implementations
`client.createRoom(scenarioId, adminToken?, ownerRole?)`	`Promise<RoomCredentials>`	Trusted provisioning; owner has wildcard grants
`client.room(roomId, token)`	`RoomClient`	New local handle; no request or socket yet
`client.resumeRoom(roomId, token)`	`Promise<{room, snapshot}>`	New handle plus authorized snapshot; does not subscribe
`room.dispose()`	`void`	Permanently closes this handle's local stream
`room.closeRoom()`	`Promise<void>`	Authorized remote room close; disposes the stream after a successful response

scenarioId records product context; the standalone server does not use it to install a scenario, provision channels, or attach agents.

RoomClient exposes readonly baseUrl, roomId, and token. Treat the token as a credential when inspecting or serializing objects. Implementation: client.ts.

Publication and channels

TypeScript

type PublishEvent<T> = {
  clientEventId: string;
  type: string;
  channelId?: string;
  causationId?: string;
  correlationId?: string;
  visibility?: Visibility;
  payload: T;
};

Method	Result	Notes
`room.publish<T>(input)`	`Promise<EventEnvelope<T>>`	Explicit client event ID
`room.createChannel({id?, type, direction, media_binding?})`	`Promise<Channel>`	Creates a remote channel definition
`room.channel(channelId)`	`ChannelClient`	Local handle only; requires a nonblank ID
`channel.publish<T>(type, payload, options?)`	`Promise<EventEnvelope<T>>`	Options: `clientEventId`, `causationId`, `correlationId`, `visibility`; defaults the ID to a UUID
`channel.subscribe(options)`	`RoomSubscription`	Forces the selector to this channel ID; accepts subscription options except `selector`

For a channel and event-type selection, use room.subscribe({selector: {channelIds, eventTypes}, ...}). Do not pass a second selector through the channel helper. Read publication semantics before implementing retries.

Subscriptions

Import SubscribeOptions from @rmc/client for the complete TypeScript definition.

Option	Purpose
`id`	Optional local subscription ID
`afterSeq`	Resume after this processed position; defaults to zero
`selector`	Optional `channelIds`, `channelTypes`, and `eventTypes` arrays
`signal`	Optional `AbortSignal` for cleanup
`onEvent`	Required callback; return or await asynchronous processing
`onCheckpoint`	Optional processed-cursor callback; may return a promise
`onError`	Optional error callback
`onStateChange`	Optional connection/subscription state callback

room.subscribe(options) returns immediately. RoomSubscription exposes readonly id, cursor, closed, and close(): void. IDs must be nonblank, unique among active subscriptions on the room handle, and no longer than 128 UTF-8 bytes. afterSeq defaults to zero and must be a nonnegative safe integer.

SubscriptionState is connecting | authenticating | live | reconnecting | closed. Callbacks run serially per subscription. Processing failures and overflow close the affected consumer; transport reconnection retains handles and processed cursors. See delivery and recovery, stream.ts, and stream tests.

Reads, state, and artifacts

Method	Result	Notes
`room.snapshot()`	`Promise<RoomSnapshot>`	Authorized current projections; concurrent replay can overlap newer versions
`room.events(afterSeq = 0)`	`Promise<EventEnvelope[]>`	One scanned page; SDK does not expose `X-RMC-Cursor`
`room.topology()`	`Promise<RuntimeTopology>`	Existing basic diagnostics; requires `room:inspect` on `*`
`room.patchState<T>(key, patch, expectedVersion?, visibility?)`	`Promise<StateDocument<T>>`	Merge patch; generates a client event ID per call
`room.putArtifact<T>({id, type, content, status?, expectedVersion?, visibility?})`	`Promise<Artifact<T>>`	Default status `current`; generates a client event ID per call

An empty Go slice can be encoded as null, despite an array annotation in the current SDK. Normalize collection reads with ?? [] at your boundary. The SDK decodes HTTP JSON into typed values without runtime schema validation. Use your application's validator where untrusted payloads enter a model.

Participants, work, and tools

Method	Result	Notes
`room.invite(role, grants)`	`Promise<{participant, token}>`	Privileged provisioning
`room.delegate(request)`	`Promise<DelegationHandle>`	Snake_case `DelegationRequest`; explicit idempotency key
`room.cancelDelegation(id)`	`Promise<void>`	Cancellation by delegation ID
`room.ask(question, idempotencyKey?)`	`Promise<DelegationHandle>`	Generates an idempotency key if omitted
`room.confirmTool(name, arguments)`	`Promise<string>`	Returns a confirmation ID
`room.invokeTool<T>(name, arguments, confirmationId?)`	`Promise<T>`	Required grants and confirmation depend on the tool descriptor

Participant revocation is currently available through HTTP DELETE /v1/rooms/{room}/participants/{participant}; there is no SDK wrapper. Tool confirmation is a separate explicit step; a confirmation ID does not replace the tool's required action grant. See authorization and background work.

Media and voice

Method	Result	Notes
`room.createMediaSession(adapter = "livekit", options?)`	`Promise<MediaJoinCredential>`	Options contain `publishChannelIds`; omission differs from an empty list
`room.mediaPresence()`	`Promise<MediaPresenceSnapshot>`	Authorized existing presence projection
`room.refreshMediaPresence(adapterId)`	`Promise<MediaPresenceSnapshot>`	Requests a provider metadata refresh
`room.createVideoChannel(id = "video", direction = "input")`	`Promise<Channel>`	Creates `video.observation`, not a native media input
`room.createMediaVideoChannel(id, mediaBinding, direction = "input")`	`Promise<Channel>`	Creates a bound `media.video` input
`room.publishVideoObservation(channelId, observation, options?)`	`Promise<EventEnvelope<VideoObservation>>`	Options: `clientEventId`, `visibility`; requires valid observation content
`room.connectVoice(options?)`	`Promise<VoiceConnection>`	Owns a separate native voice lifetime
`room.voiceSession(id)`	`Promise<VoiceSession>`	Reads the session record

VoiceConnection exposes id, model, epoch, state, peer, localStream, and dataChannel, plus async interrupt(), reportPlayback(itemId, audioEndMs, responseId?), reconnect(), and close().

Common VoiceOptions are channelId, audioElement, signal, mediaConstraints, resumeCursor, and onStateChange. Additional provider, timing, and testing options are defined in voice.ts. Read LiveKit and voice for token scope and cleanup before connecting.

Error handling and wire shapes

HTTP helpers reject with a plain Error using the response's error message when present. They do not expose status fields on a custom SDK error class. Use a purpose-built HTTP call when your workflow must distinguish raw status/body details, as in the history helper.

Inputs such as PublishEvent and selectors use camelCase. Envelopes and persisted resource shapes retain snake_case. The envelope version is rmc.dev/v1alpha1; it is separate from WebSocket protocol version 2. See types.ts and the wire reference.

TypeScript SDK reference