Toju/docs-site/docs/plugin-development/api-reference.md

sidebar_position

sidebar_position
4

Plugin API Reference

TojuClientPluginApi is the object passed to a plugin activation context. The runtime freezes the API object before passing it to plugin code.

Activation Types

interface TojuPluginDisposable {
  dispose: () => void;
}

interface TojuPluginActivationContext {
  api: TojuClientPluginApi;
  manifest: TojuPluginManifest;
  pluginId: string;
  subscriptions: TojuPluginDisposable[];
}

interface TojuClientPluginModule {
  activate?: (context: TojuPluginActivationContext) => Promise<void> | void;
  deactivate?: (context: TojuPluginActivationContext) => Promise<void> | void;
  onPluginDataChanged?: (context: TojuPluginActivationContext, event: unknown) => Promise<void> | void;
  onServerRequirementsChanged?: (context: TojuPluginActivationContext, snapshot: PluginRequirementsSnapshot) => Promise<void> | void;
  ready?: (context: TojuPluginActivationContext) => Promise<void> | void;
}

Profiles

interface PluginApiProfileUpdate {
  description?: string;
  displayName: string;
}

interface PluginApiAvatarUpdate {
  avatarHash: string;
  avatarMime: string;
  avatarUrl: string;
}

Method	Capability	Description
profile.getCurrent()	profile.read	Returns the current User or null.
profile.update(profile)	profile.write	Updates display name and optional description.
profile.updateAvatar(avatar)	profile.write	Updates avatar URL, MIME type, and hash metadata.

Users and Roles

Method	Capability	Description
users.getCurrent()	users.read	Returns current User or null.
users.list()	users.read	Returns known users.
users.readMembers()	users.read	Returns active room members.
users.setRole(userId, role)	roles.manage	Updates a user's role.
users.kick(userId)	users.manage	Kicks a user.
users.ban(userId, reason?)	users.manage	Bans a user with optional reason.
roles.list()	roles.read	Returns room roles.
roles.setAssignments(assignments)	roles.manage	Replaces role assignments.

Server

interface PluginApiServerSettingsUpdate {
  description?: string;
  isPrivate?: boolean;
  maxUsers?: number;
  name?: string;
  password?: string;
  topic?: string;
}

interface PluginApiPluginUserRequest {
  avatarUrl?: string;
  displayName: string;
  id?: string;
}

Method	Capability	Description
server.getCurrent()	server.read	Returns the current Room or null.
server.registerPluginUser(request)	users.manage	Adds a plugin-owned user and returns its id.
server.updatePermissions(permissions)	server.manage	Updates partial room permissions.
server.updateSettings(settings)	server.manage	Updates room settings.

Channels

interface PluginApiChannelRequest {
  id?: string;
  name: string;
  position?: number;
}

Method	Capability	Description
channels.list()	channels.read	Returns current room channels.
channels.select(channelId)	channels.read	Selects a channel.
channels.addAudioChannel(request)	channels.manage	Adds a voice channel.
channels.addVideoChannel(request)	channels.manage	Registers a video channel section.
channels.rename(channelId, name)	channels.manage	Renames a channel.
channels.remove(channelId)	channels.manage	Removes a channel.

Messages

interface PluginApiMessageAsPluginUserRequest {
  channelId?: string;
  content: string;
  pluginUserId: string;
}

Method	Capability	Description
messages.readCurrent()	messages.read	Returns current visible messages.
messages.send(content, channelId?)	messages.send	Sends a message and returns the created Message.
messages.sendAsPluginUser(request)	messages.send	Emits a message from a registered plugin user.
messages.edit(messageId, content)	messages.editOwn	Edits a plugin message.
messages.delete(messageId)	messages.deleteOwn	Deletes a plugin message.
messages.moderateDelete(messageId)	messages.moderate	Performs a moderation delete.
messages.sync(messages)	messages.sync	Syncs an array of messages into state.

Events

interface PluginApiEventSubscription {
  eventName: string;
  handler: (event: PluginEventEnvelope) => void;
}

interface PluginEventEnvelope<TPayload = unknown> {
  emittedAt?: number;
  eventId?: string;
  eventName: string;
  payload: TPayload;
  pluginId: string;
  serverId: string;
  sourcePluginUserId?: string;
  sourceUserId?: string;
  type: 'plugin_event';
}

Method	Capability	Description
events.publishServer(eventName, payload)	events.server.publish	Sends a declared plugin event through the signaling server.
events.subscribeServer(subscription)	events.server.subscribe	Subscribes to a declared server plugin event.
events.publishP2p(eventName, payload)	events.p2p.publish	Sends a declared plugin event over peer paths.
events.subscribeP2p(subscription)	events.p2p.subscribe	Registers a P2P event subscription.

Message Bus

interface PluginApiMessageBusEnvelope {
  channelId?: string;
  eventId: string;
  messages?: Message[];
  payload?: unknown;
  pluginId: string;
  roomId: string;
  sentAt: number;
  sourcePeerId?: string;
  sourceUserId?: string;
  topic: string;
}

interface PluginApiMessageBusLatestRequest {
  channelId?: string;
  includeDeleted?: boolean;
  limit?: number;
  sinceTimestamp?: number;
  targetPeerId?: string;
  topic?: string;
}

interface PluginApiMessageBusPublishRequest extends PluginApiMessageBusLatestRequest {
  includeLatestMessages?: boolean;
  includeSelf?: boolean;
  payload?: unknown;
  topic: string;
}

interface PluginApiMessageBusSubscription {
  channelId?: string;
  handler: (event: PluginApiMessageBusEnvelope) => void;
  latestMessageLimit?: number;
  replayLatest?: boolean;
  topic?: string;
}

Method	Capability	Description
messageBus.publish(request)	events.p2p.publish, optionally messages.read	Publishes a plugin-bus event, optionally including latest messages.
messageBus.sendLatestMessages(request?)	events.p2p.publish and messages.read	Sends a latest-message snapshot.
messageBus.subscribe(subscription)	events.p2p.subscribe, optionally messages.read	Subscribes to plugin-bus events, optionally replaying latest messages.

P2P and Media

interface PluginApiAudioClipRequest {
  volume?: number;
  url: string;
}

interface PluginApiCustomStreamRequest {
  label?: string;
  stream: MediaStream;
}

Method	Capability	Description
p2p.connectedPeers()	p2p.data	Returns connected peer ids.
p2p.broadcastData(eventName, payload)	p2p.data	Broadcasts plugin data.
p2p.sendData(peerId, eventName, payload)	p2p.data	Sends plugin data targeted to a peer.
media.playAudioClip(request)	media.playAudio	Plays an audio URL at optional volume.
media.addCustomAudioStream(request)	media.addAudioStream	Contributes an audio MediaStream.
media.addCustomVideoStream(request)	media.addVideoStream	Registers a video MediaStream contribution.
media.setInputVolume(volume)	audio.volume	Sets local input volume.
media.setOutputVolume(volume)	audio.volume	Sets local output volume.

Storage

Method	Capability	Description
clientData.read(key)	storage.local	Reads async plugin-local data.
clientData.write(key, value)	storage.local	Writes async plugin-local data.
clientData.remove(key)	storage.local	Removes async plugin-local data.
serverData.read(key)	storage.serverData.read	Reads local per-user/per-server data.
serverData.write(key, value)	storage.serverData.write	Writes local per-user/per-server data.
serverData.remove(key)	storage.serverData.write	Removes local per-user/per-server data.
storage.get(key)	storage.local	Legacy synchronous local read.
storage.set(key, value)	storage.local	Legacy synchronous local write.
storage.remove(key)	storage.local	Legacy synchronous local remove.

UI Contributions

interface PluginApiActionContribution {
  icon?: string;
  label: string;
  run: () => Promise<void> | void;
}

interface PluginApiPageContribution {
  label: string;
  path: string;
  render: () => HTMLElement | string;
}

interface PluginApiPanelContribution {
  label: string;
  order?: number;
  render: () => HTMLElement | string;
}

interface PluginApiSettingsPageContribution {
  label: string;
  order?: number;
  render: () => HTMLElement | string;
  settingsKey?: string;
}

interface PluginApiChannelSectionContribution {
  label: string;
  order?: number;
  type?: 'audio' | 'custom' | 'video';
}

interface PluginApiEmbedRendererContribution {
  embedType: string;
  render: (payload: unknown) => HTMLElement | string;
}

interface PluginApiDomMountRequest {
  element: HTMLElement;
  position?: InsertPosition;
  target: Element | string;
}

Method	Capability	Description
ui.registerAppPage(id, contribution)	ui.pages	Adds a plugin app page.
ui.registerSettingsPage(id, contribution)	ui.settings	Adds a plugin settings page.
ui.registerSidePanel(id, contribution)	ui.sidePanel	Adds a side panel.
ui.registerChannelSection(id, contribution)	ui.channelsSection	Adds a channel section.
ui.registerComposerAction(id, contribution)	ui.pages	Adds a composer action.
ui.registerProfileAction(id, contribution)	ui.pages	Adds a profile action.
ui.registerToolbarAction(id, contribution)	ui.pages	Adds a toolbar action.
ui.registerEmbedRenderer(id, contribution)	ui.embeds	Adds an embed renderer.
ui.mountElement(id, request)	ui.dom	Mounts plugin-owned DOM into a target element or selector.