Bot SDK (@fluffwire/bot-sdk)

The official TypeScript/JavaScript SDK for building Fluffwire bots. It wraps the REST API and WebSocket gateway so you can focus on your bot's logic.

• npm: @fluffwire/bot-sdk
• Source: github.com/Fluffwire/fluffwire-sdk
• License: AGPL-3.0

Installation

npm install @fluffwire/bot-sdk

Requires Node.js 18 or newer.

Quick Start

import { FluffwireClient } from '@fluffwire/bot-sdk'

const client = new FluffwireClient({
  token: process.env.BOT_TOKEN!,
})

client.on('ready', () => {
  console.log('Bot is online!')
})

client.on('messageCreate', async (msg) => {
  if (msg.author.isBot) return
  if (msg.content === '!ping') {
    await client.sendMessage(msg.channelId, 'Pong! 🏓')
  }
})

await client.connect()

Constructor Options

new FluffwireClient(options: ClientOptions)

Option	Type	Default	Description
token	string	required	Your bot token (with or without the Bot prefix)
baseUrl	string	https://app.fluffwire.com/api	Override the REST API base URL
wsUrl	string	wss://app.fluffwire.com/ws	Override the WebSocket gateway URL

Events

Listen to gateway events with client.on(event, handler):

Event	Payload	Description
ready	—	Bot is connected and authenticated
messageCreate	Message	A new message was sent in any visible channel
messageUpdate	Message	A message was edited
messageDelete	{ id, channelId }	A message was deleted
reactionAdd	{ messageId, channelId, userId, emoji }	A reaction was added
reactionRemove	{ messageId, channelId, userId, emoji }	A reaction was removed
commandInvoke	CommandInvokePayload	A slash command was invoked by a user
error	Error	A connection or protocol error occurred

Methods

connect()

await client.connect(): Promise<void>

Opens the WebSocket connection and resolves when ready is received. Automatically handles the IDENTIFY handshake and heartbeating.

disconnect()

client.disconnect(): void

Closes the WebSocket connection cleanly.

sendMessage(channelId, content)

await client.sendMessage(channelId: string, content: string | SendMessageOptions): Promise<Message>

Send a plain text message, or a structured message with attachments:

// Plain text
await client.sendMessage(channelId, 'Hello!')

// With attachment
await client.sendMessage(channelId, {
  content: 'Here is a file:',
  attachments: [{ url, filename: 'report.pdf' }],
})

toggleReaction(channelId, messageId, emoji)

await client.toggleReaction(channelId: string, messageId: string, emoji: string): Promise<void>

Adds a reaction if the bot hasn't reacted yet, or removes it if it has.

sendTyping(channelId)

await client.sendTyping(channelId: string): Promise<void>

Shows the bot as typing. Disappears after ~5 seconds or when a message is sent.

uploadFile(file, filename)

await client.uploadFile(file: Buffer | Blob, filename: string): Promise<{ url: string }>

Uploads a file and returns its hosted URL, which can then be passed as an attachment URL.

registerCommand(options)

await client.registerCommand(options: RegisterCommandOptions): Promise<BotCommand>

Registers a slash command for a server. Options:

Field	Type	Description
name	string	Command name (lowercase, no spaces)
description	string	Shown in the command picker
serverId	string	Server to register the command on
options	CommandOption[]	Optional list of command parameters

listCommands() / updateCommand() / deleteCommand()

await client.listCommands(): Promise<BotCommand[]>
await client.updateCommand(commandId: string, options: Partial<RegisterCommandOptions>): Promise<BotCommand>
await client.deleteCommand(commandId: string): Promise<void>

Manage existing registered commands.

Examples

The SDK repository includes runnable examples covering common patterns:

File	What it shows
01-connect.ts	Minimal connect + ready event
02-send-message.ts	Send text and attachment messages
03-receive-messages.ts	Echo bot, message edit/delete events
04-slash-commands.ts	Register commands and handle invocations
05-reactions-and-typing.ts	React to messages, show typing indicator
06-file-upload.ts	Upload a local file and attach to message
07-reaction-events.ts	Listen to reactionAdd/reactionRemove events
08-error-handling.ts	API errors, partial failures, graceful shutdown
09-manage-commands.ts	List, update, and delete registered commands

Run any example with:

BOT_TOKEN=your_token CHANNEL_ID=your_channel_id npx tsx examples/02-send-message.ts

Reconnection

The SDK automatically reconnects when the WebSocket closes unexpectedly (non-1000 close codes). It will attempt to resume the session using the stored sessionId and sequence number. If resumption fails, it falls back to a fresh IDENTIFY.

Raw API Access (without SDK)

Prefer using the SDK, but if you need lower-level access see the REST API reference and WebSocket Gateway pages for the raw protocol documentation.