Server plugin API

This is the reference. Server plugins is the page that teaches the shape, and plugin pairs covers talking to a copy of yourself in somebody's client.

A plugin starts by exporting activate, or a default export, and is called with the object below.

export function activate(api) {
  api.log.info(`${api.id} is up`);
}

Capabilities

What a manifest may ask for. A name this server has never heard of is dropped rather than refused, so a plugin written against a newer Gryt still loads.

The manifest

manifest.json, beside your entry point.

api

id

id: string

This plugin's own id, so it does not have to hard-code the folder name.

capabilities

capabilities: readonly PluginCapability[]

What the manifest declared, normalised. Readable so a plugin can degrade.

on()

on<E extends PluginEventName>(event: E, handler: PluginEventHandler<E>): void

Subscribe to an event. Throws if the manifest did not ask for the capability behind it.

Throwing rather than returning false, and throwing at subscribe rather than failing silently at delivery: a plugin that never receives an event it thought it had asked for is a bad afternoon, and the stack trace at startup names the line.

moderation

moderation: PluginModeration

Kick and ban. Throws on access if the manifest did not declare moderation, rather than handing back an object whose every call refuses — a plugin should find out it has not been given this when it reaches for it, not on the first member it tries to act on.

The calls themselves return an outcome rather than throwing. A refusal there is an ordinary answer — the member is a moderator, or already gone — and a plugin should be able to log it and carry on.

messaging

messaging: PluginMessaging

The pipe to the client half of this plugin. Throws on access if the manifest did not declare messaging.

What arrives on it was written by a member's client. Check it. The transport caps the size and the rate and nothing else — the shape is the plugin's to establish, and assuming its own client half is on the other end is the mistake this note exists for.

log

log: PluginLogger

Goes to the server log, prefixed with the plugin id.

Events

api.on(name, handler). Subscribing throws if the manifest did not declare the capability behind the event, rather than failing quietly at delivery.

message:created

Needs messages:read.

api.on("message:created", (payload) => {})

member:joined

Needs members:read.

api.on("member:joined", (payload) => {})

member:left

Needs members:read.

api.on("member:left", (payload) => {})

api.moderation

Needs moderation. Reading the property throws without it, rather than handing back an object whose every call refuses.

A call returns an outcome rather than throwing. A refusal is an ordinary answer — the member can moderate, or is already gone — and a plugin should log it and carry on.

kick()

kick(serverUserId: string, options?: { reason?: string }): Promise<ModerationOutcome>

Remove somebody from the server. They can come back.

ban()

ban( serverUserId: string, options?: { reason?: string; durationMs?: number }, ): Promise<ModerationOutcome>

Remove somebody and stop them returning.

deleteMessage()

deleteMessage(channelId: string, messageId: string): Promise<ModerationOutcome>

Take a message down. Usually the more proportionate answer — most spam wants the post gone rather than the person.

Channels only. A direct message is between two people and a plugin the operator installed has no business in it, the same rule that keeps DMs out of message:created.

api.messaging

Needs messaging. The pipe to the client half of this plugin.

on()

on(topic: string, handler: PluginMessageHandler): void

Hear what the client half of this plugin sends.

send()

send(topic: string, data: unknown, target?: SendTarget): boolean

Send to the client halves of this plugin. Returns false when the message was refused — too big, or a topic that is not one — and says why in the log.

Not a promise: this hands the message to socket.io and returns. There is no delivery to wait for and nothing useful to do about a client that is not listening.

What a handler is given

What Gryt drops before you see it

A __proto__, constructor or prototype key is refused as well, and so is anybody sending more than thirty messages in ten seconds.