Bot API

This is the reference. Writing a bot is the page that teaches the shape: the handshake, waiting to be approved, and what a bot does when an admin says no.

Everything below is exported from @gryt/bot. Nothing else in the package is public.

import { GrytBot, parseCommand, splitArgs, createIdentity, loadIdentity, PERMISSIONS_BEFORE_CATALOGUE } from "@gryt/bot";

GrytBot

A bot on one Gryt server. It joins like any other client and is a member like any other: no bot account type and no bypass, so what it may do is what its role says.

can()

can(permission: Permission): boolean

False before ready. True for a permission the server's catalogue does not have — that is a server older than the permission, not a refusal.

command()

command(name: string, handler: (ctx: CommandContext) => void | Promise<void>, options: CommandOptions = {}): this

Register a command. Later registrations of the same name replace earlier.

start()

start(): Promise<ServerInfo>

Connect, join, and resolve once the server has said who this bot is. On a first run it does not resolve: the bot is waiting at the door. Listen for waiting, then ready.

stop()

stop(): Promise<void>

Leave, and stop reconnecting.

send()

send(conversationId: string, text: string): Promise<void>

Post in a channel. Throws before sending if the bot lacks send_messages, naming the permission, so the stack trace points at the call rather than a socket handler.

react()

react(conversationId: string, messageId: string, reactionSrc: string): Promise<void>

delete()

delete(conversationId: string, messageId: string, opts: { own?: boolean } = {}): Promise<void>

Delete a message. Its own is delete_own_messages; anybody else's is manage_messages, and the caller says which, because the bot may not know who sent it.

fetch()

fetch(conversationId: string, limit = 50): Promise<void>

Ask for the last N messages in a channel. Answered on the message event.

GrytBotEvents

GrytBotOptions

parseCommand

Which command a message invokes, if any. Case-insensitive on the command word, because somebody will type !Help and being right about it helps nobody.

parseCommand(text: string, prefix: string): { name: string; rest: string } | null

splitArgs

splitArgs(rest: string): string[]

CommandContext

CommandOptions

RegisteredCommand

createIdentity

Mint a new identity. The bot this belongs to has never been seen anywhere.

createIdentity(): Promise<{ identity: BotIdentity; privateJwk: JWK; }>

loadIdentity

The second run must be the same bot: same id, same role, same history. Written 0o600 — anyone who can read this file can be this bot.

loadIdentity(path: string): Promise<BotIdentity>

PERMISSIONS_BEFORE_CATALOGUE

Stands in for the catalogue on a server too old to publish one, so an absent permission is not read as a refusal. Frozen: it describes a release that has already happened.

PERMISSIONS_BEFORE_CATALOGUE: readonly Permission[] = [ "send_messages", "attach_files", "add_reactions", "join_voice", "speak", "share_video", "share_screen", "change_nickname", "change_avatar", "create_invite", "manage_invites", "manage_messages", "kick_members", "ban_members", "mute_members", "manage_reports", "manage_join_requests", "manage_channels", "manage_emojis", "manage_webhooks", "manage_roles", "manage_server", "view_audit_log", ]

BotIdentity

Attachment

Channel

ServerRefusal

Why the server refused something. The machine-readable half is error; code is accepted too, because this SDK reached for that name first and the mistake read as a crash.

Member

Message

Permission

A permission id. The server owns the list; see GrytBot.permissions.

export type Permission = string;

ServerInfo