The client is an event emitter with on, once, off, emit, removeAllListeners and
listenerCount. Event names come from the Events enum; ClientEvents types each listener.
import { Events } from '@strafechat/strafe.js';
client.on(Events.SpaceMemberAdd, async (member) => {
const room = member.space.systemRoom;
if (room?.isSendable()) await room.send(`Welcome, ${member.toString()}!`);
});There are no intents. The bot receives every event about the spaces, rooms and threads it can see.
| Event | Listener arguments | When |
|---|---|---|
ClientReady ('clientReady', also 'ready') |
client: Client<true> |
First READY; once per login() |
GatewayReady |
none | Every READY, reconnects included |
Reconnecting |
none | The connection dropped; a reconnect is scheduled |
Reconnected |
none | A reconnect reached READY and caches were reconciled |
Invalidated |
reason: string |
The session ended for good; the client stopped |
MessageCreate |
message |
A message was sent, including system and encrypted ones |
MessageUpdate |
oldMessage, newMessage |
A message was edited |
MessageDelete |
message |
A message was deleted |
MessageReactionAdd |
reaction, user |
Someone reacted |
MessageReactionRemove |
reaction, user |
Someone removed a reaction |
RoomPinsUpdate |
room, date: Date | null, details |
A message was pinned or unpinned (details.messageId, pinned, userId) |
TypingStart |
typing |
Someone started typing |
SpaceCreate |
space |
The bot joined or was installed in a space |
SpaceUpdate |
oldSpace, newSpace |
A space's settings changed |
SpaceDelete |
space |
The bot left or was removed, or the space was deleted |
SpaceMemberAdd |
member |
Someone joined a space |
SpaceMemberUpdate |
oldMember, newMember |
Roles, nickname or space profile changed |
SpaceMemberRemove |
member |
Someone left, or was kicked or banned |
RoomCreate, RoomDelete |
room |
A room was created or deleted, or became visible or invisible |
RoomUpdate |
oldRoom, newRoom |
Settings, position or permission overrides changed |
RoleCreate, RoleDelete |
role |
A role was created or deleted |
RoleUpdate |
oldRole, newRole |
A role changed |
ThreadCreate |
thread, newlyCreated: boolean |
A thread was created (false when an existing one became visible) |
ThreadUpdate |
oldThread, newThread |
A thread changed |
ThreadDelete |
thread |
A thread was deleted |
ThreadMembersUpdate |
added, removed, thread |
People joined or left a thread |
EmojiCreate, EmojiDelete |
emoji |
A custom emoji was added or deleted |
EmojiUpdate |
oldEmoji, newEmoji |
A custom emoji was renamed |
PresenceUpdate |
oldPresence | null, newPresence |
Status or activity changed |
UserUpdate |
oldUser, newUser |
A profile changed |
VoiceStateUpdate |
oldState, newState |
Someone joined, left, moved or was muted in voice |
Raw |
packet |
Every gateway frame |
Debug |
message: string |
Diagnostics |
Warn |
message: string |
A non-fatal problem, such as a gateway error frame or an unsupported option |
Error |
error: Error |
An error from a listener or from event handling |
Other gateway events, such as read receipts and call signalling, arrive through Events.Raw.
Update events pass a copy of the object before the change and the live cache entry after it. The live entry is patched in place, so copy values you want to keep.
client.on(Events.SpaceMemberUpdate, (oldMember, newMember) => {
const added = newMember.roles.cache.filter((role) => !oldMember.roles.cache.has(role.id));
if (added.size > 0) console.log(`${newMember.displayName} got ${added.map((r) => r.name).join(', ')}`);
});Events about uncached things still fire, with partial objects. Check partial and fetch when
you need more:
client.on(Events.MessageReactionAdd, async (reaction, user) => {
const message = reaction.message.partial ? await reaction.message.fetch() : reaction.message;
console.log(`${user.id} reacted ${reaction.emoji.toString()} to ${message.id}`);
});- A partial message has
id,roomandspace.authorandcontentarenulluntil fetched. A deleted uncached message stays partial. - A reaction may lack its
count;reaction.fetch()re-reads the message. oldMemberinSpaceMemberUpdateand the member inSpaceMemberRemoveare partial when the member was not cached.
Partials are always on; there is no partials option.
READY carries spaces, roles, rooms, emojis and voice states, but no member lists.
space.members.cache starts empty. Fetch it once if you need it:
client.on(Events.ClientReady, async (ready) => {
for (const space of ready.spaces.cache.values()) await space.members.fetch();
});message.member is null until the author's member is cached.
The client reconnects on its own with exponential backoff (1 second, doubling, up to a minute; set
ws.reconnectDelay and ws.maxReconnectDelay) and emits Reconnecting.
Strafe has no session resume. Each reconnect gets a fresh READY, and the client reconciles its
caches:
- Spaces, rooms and threads that changed while offline emit
SpaceCreate/SpaceDelete,RoomCreate/RoomDeleteandThreadDelete. ThenGatewayReadyandReconnectedfire.ClientReadydoes not fire again. - A cached thread missing from
READYis markedarchivedinstead of deleted. - Cached objects are patched in place. Settings changes made while offline emit no event.
- Missed messages are not replayed. Use
room.messages.fetch({ after: lastSeenId }). - Member lists may be stale. Fetch them again after
Reconnectedif you depend on them.
If the token is reset or the account is banned, the client emits Invalidated and stops.
client.ws.ping is the last round-trip time in milliseconds (-1 before the first).
client.ws.status is the connection state. Raw payload types are exported as
GatewayDispatchDataMap and GatewayReceivePayload.
client.on(Events.Debug, (line) => console.debug(line));
client.on(Events.Warn, (line) => console.warn(line));Use ClientEvents to type one handler per file:
// events/messageCreate.ts
import { Events, type ClientEvents } from '@strafechat/strafe.js';
export const name = Events.MessageCreate;
export async function execute(...[message]: ClientEvents[typeof name]): Promise<void> {
if (message.content === '!hello') await message.reply('Hello!');
}// index.ts
import * as messageCreate from './events/messageCreate.js';
client.on(messageCreate.name, messageCreate.execute);