Bot SDK Reference

Overview

@frevvu/bot-sdk is a lightweight, event-driven wrapper over Frevvu's bot gateway. There's no persistent WebSocket connection on the bot side — every poll loop is a plain HTTP request, which keeps a bot runnable from any language runtime that can speak HTTP and JSON, and keeps this SDK's own surface small enough to audit against the backend's Rust source directly.

A bot account is a real member of every server it's invited to — it can send messages, attach rich embeds, add interactive buttons and select menus, open popup forms, register slash commands, join voice channels, and optionally end-to-end encrypt what it sends. FrevvuBotClient is the class you'll spend most of your time with; it wraps a lower-level RestClient and manages polling for you.

Installation

The SDK is not yet published to npm — package.json has no publishConfig, and it's intended for local/workspace consumption for now. Point your bot project at the package directory with a file: dependency:

{
  "dependencies": {
    "@frevvu/bot-sdk": "file:../path/to/frevvu/bot-sdk"
  }
}

Then install as usual (npm install) and build the SDK once if its dist/ folder isn't already built:

# inside the bot-sdk package itself
npm run build

Quickstart

Get a bot token from the Developer Portal (Bot tab → reveal token), then:

import { FrevvuBotClient } from "@frevvu/bot-sdk";

const bot = new FrevvuBotClient({
  token: process.env.BOT_TOKEN,
  baseUrl: "https://your-instance.example",
});

bot.on("error", (err) => console.error("[bot error]", err));

const me = await bot.start();
console.log(`Logged in as ${me.username}`);

// bot.on("message", ...) is never emitted — watch() is the real
// way to receive messages. Watch every text channel the bot can see.
for (const server of me.servers) {
  for (const channel of server.channels) {
    if (channel.kind !== "text") continue;
    bot.channels.watch(channel.id, (msg) => {
      const content = msg.content;
      if (content.type === "text" && content.text === "!ping") {
        bot.channels.send(channel.id, { type: "text", text: "Pong!" });
      }
    });
  }
}

Run it with node --env-file=.env dist/index.js (or any dotenv loader of your choice) after compiling with tsc. That's a complete, working bot — everything past this point is building on the same three ideas: watch() to receive, send()/edit() to reply, and typed events for everything else.

FrevvuBotClient

The main entry point. Construct one, attach event handlers, call start().

Constructor options

Properties

Methods

Events

All events are plain EventEmitter emissions — bot.on("eventName", handler).

BotIdentity shape

interface BotIdentity {
  id: string;
  username: string;
  shown_name: string | null;
  avatar: string | null;
  servers: {
    id: string;
    name: string;
    channels: { id: string; name: string; kind: string }[];
  }[];
}

Messages & ChannelsApi

bot.channels is how a bot sends, edits, and receives messages.

MessageOut shape

interface MessageOut {
  id: string;
  channel_id: string;
  user_id: string;
  content: unknown;  // see "Message content shapes" below
  timestamp: string;
}

content is typed as unknown on purpose — the SDK doesn't police what shape a message carries, it only transports it. Cast it yourself against the shapes documented next.

Message content shapes

Every shape below is what the backend actually validates server-side (see embeds.rs/components.rs) — a message that doesn't match gets rejected with a 400, so these limits are real, not aspirational.

Plain text

{ type: "text", text: string }

Embed (rich card)

{
  type: "embed",
  embed: {
    title?: string,
    description?: string,
    url?: string,           // makes the title a link
    color?: string,         // "#rrggbb"
    author?: { name: string, url?: string, icon_url?: string },
    thumbnail_url?: string,
    image_url?: string,
    footer?: { text: string, icon_url?: string },
    timestamp?: string,     // ISO 8601
    fields?: { name: string, value: string, inline?: boolean }[],
  }
}

Components — buttons & select menus

components is a top-level sibling of type, not a content type of its own — a bot can attach interactive components to a plain-text message, an embed, or anything else:

{
  type: "text",           // or "embed", or anything — components ride alongside
  text: "Pick one:",
  components: [
    {
      buttons: [
        { label: "Confirm", style: "primary", custom_id: "confirm" },
        { label: "Cancel", style: "danger", custom_id: "cancel" },
        { label: "Docs", style: "link", url: "https://example.com" },
      ]
    },
    {
      select_menu: {
        custom_id: "color",
        placeholder: "Pick a color…",
        options: [
          { label: "Purple", value: "purple", description: "#8B5CF6" },
          { label: "Green", value: "green" },
        ],
        min_values: 1,
        max_values: 1,
      }
    }
  ]
}

A row is either buttons or select_menu, never both — mirroring Discord's own action-row constraint.

See Buttons & select menus below for how clicks/selections reach your bot.

Slash command invocation (received)

When a user runs a registered slash command, it arrives through the exact same channel — watch() delivers it like any other message, just shaped differently:

{
  type: "command",
  command: string,                        // the command name
  command_bot_id: string,
  command_options?: Record<string, string>, // option name -> value
}

Attachments (received)

{
  type: "attachments",
  files: { url: string, name: string, size: number, content_type: string }[],
}

Buttons & select menus

Attach components to any message (see above), then listen for the interaction event to find out when someone uses them.

bot.on("interaction", (i) => {
  if (i.custom_id === "confirm") {
    bot.channels.send(i.channel_id, { type: "text", text: `Confirmed by @${i.username}` });
  }
});

InteractionOut shape

interface InteractionOut {
  id: string;
  message_id: string;
  channel_id: string;
  user_id: string;
  username: string;         // see note below
  shown_name: string | null;
  custom_id: string;
  values?: string[];        // present only for a select-menu interaction
}

// Narrows an InteractionOut to one with `values`:
function isSelectInteraction(i: InteractionOut): i is InteractionOut & { values: string[] };

Use isSelectInteraction(i) to safely read i.values:

import { isSelectInteraction } from "@frevvu/bot-sdk";

bot.on("interaction", (i) => {
  if (i.custom_id === "color" && isSelectInteraction(i)) {
    bot.channels.send(i.channel_id, { type: "text", text: `@${i.username} picked ${i.values[0]}` });
  }
});

Pagination

There's no special "paginated embed" feature on the backend — Paginator is a small SDK convenience built entirely out of ordinary buttons plus channels.edit().

import { Paginator } from "@frevvu/bot-sdk";

const pages = [
  { type: "embed", embed: { title: "Page 1 of 3", description: "…" } },
  { type: "embed", embed: { title: "Page 2 of 3", description: "…" } },
  { type: "embed", embed: { title: "Page 3 of 3", description: "…" } },
];

const paginator = new Paginator(bot, { channelId, pages });
await paginator.send();

// later, once nobody should be able to page it anymore:
paginator.stop();

PaginatorOptions

Internally it generates reserved-looking custom_ids (__paginator:<nonce>:prev/:next), listens for matching interaction events, and calls channels.edit() on each click — nothing here is special-cased by the backend, so you could hand-roll the same pattern yourself with plain buttons if you needed something Paginator doesn't cover.

Modals

A modal is a popup form your bot can open in response to a button click or select-menu choice, collect a few text fields, and get the filled-out values back.

import { showModal } from "@frevvu/bot-sdk";

bot.on("interaction", (i) => {
  if (i.custom_id === "feedback") {
    showModal(bot, i.id, {
      custom_id: "feedback-form",
      title: "Send feedback",
      components: [
        { text_input: { custom_id: "summary", label: "Summary", style: "short", required: true, max_length: 100 } },
        { text_input: { custom_id: "details", label: "Details", style: "paragraph", required: false, max_length: 1000 } },
      ],
    });
  }
});

bot.on("modalSubmit", (s) => {
  if (s.modal_custom_id === "feedback-form") {
    bot.channels.send(s.channel_id, {
      type: "text",
      text: `Thanks! Summary: ${s.fields.summary}`,
    });
  }
});

The triggering button just needs opens_modal: true so the client knows to wait briefly for a modal after the click:

{ label: "Feedback", style: "secondary", custom_id: "feedback", opens_modal: true }

ModalSpec / ComponentTextInput

interface ModalSpec {
  custom_id: string;
  title: string;
  components: { text_input: ComponentTextInput }[];
}

interface ComponentTextInput {
  custom_id: string;
  label: string;
  style?: "short" | "paragraph";
  placeholder?: string;
  required?: boolean;      // default true
  min_length?: number;
  max_length?: number;      // 4000 hard cap
  value?: string;           // pre-filled default
}

interface ModalSubmissionOut {
  id: string;
  channel_id: string;
  user_id: string;
  modal_custom_id: string;
  fields: Record<string, string>;  // text_input custom_id -> submitted value
}

Slash commands

Register the commands your bot supports; Frevvu's composer autocompletes them for members of any server the bot is in.

await bot.commands.register([
  {
    name: "ping",
    description: "Check if the bot is responsive",
  },
  {
    name: "roll",
    description: "Roll a die",
    options: [
      { name: "sides", description: "Number of sides", required: false },
    ],
  },
]);

A command invocation arrives exactly like any other message — see the "command" content shape above, delivered through whatever channel's watch() handler is listening.

Voice & music controls

A bot joins a voice channel exactly like a human does — same roster, same LiveKit room. The SDK only handles signaling; actually publishing audio is your job via any LiveKit client SDK, using the token this hands back.

const session = await bot.voice.join(channelId);
// session.token.{token, url} are what a LiveKit client SDK needs to connect

session.onCommand((command, userId) => {
  // command is one of "play" | "pause" | "skip" | "previous"
  console.log(`${userId} clicked ${command}`);
});

await session.setNowPlaying({
  title: "Song Title",
  artist: "Artist Name",
  duration_secs: 180,
  position_secs: 0,
  playing: true,
});

// when the track ends:
await session.clearNowPlaying();

// when done entirely:
await session.leave();

setNowPlaying() populates the built-in music-controls card every other client sees on this bot's voice participant tile — that's what produces the play/pause/skip/previous clicks onCommand() receives.

End-to-end encryption

Enable it to read a channel's old encrypted history. A bot that doesn't opt in still works everywhere else, it just can't read those older messages:

const bot = new FrevvuBotClient({
  token,
  baseUrl,
  e2ee: true,  // default: FileKeyStorage at .frevvu-bot/{botId}.json
});

await bot.start(); // registers this device's E2EE identity on first run

await bot.channels.send(channelId, { type: "text", text: "sent as plain text" });

With e2ee: true, watch() auto-decrypts old E2EE envelopes before calling your handler — you never see raw ciphertext in content for a channel your bot holds the key for.

Key storage

What this does not cover

• Bots are never DM or call participants in the E2EE model — a bot can only ever hold a channel key, never a DM-thread key or a call key; the backend rejects those contexts outright for a bot.
• No forward secrecy within a key epoch — same accepted tradeoff as the human client. A compromised channel key exposes everything encrypted under it until the next member-driven rotation.

Low-level RestClient

Every higher-level API (channels, commands, voice) is a thin wrapper over bot.rest. You'll rarely need this directly, but it's the full, authoritative list of what the gateway exposes.

Messages

Interactions & modals

Identity & commands

Voice

Devices / E2EE

Every request carries Authorization: Bot <token>; a non-2xx response throws with the shape METHOD PATH -> STATUS: body text.

All exports

The complete public surface of @frevvu/bot-sdk:

Plus every type used above: BotIdentity, GatewayServer, GatewayChannel, MessageOut, InteractionOut, ComponentTextInput, ModalSpec, ModalSubmissionOut, CommandDefinition, CommandOption, VoiceCommandOut, VoiceTokenOut, NowPlayingIn, DeviceKeyOut, MemberDeviceKeys, KeyStorage, E2eeEnvelope, E2eeContext, E2eeKeyDistributionMessage, E2eeKeyRequestMessage, E2eeInboxMessage, RestClientOptions, FrevvuBotClientOptions, PaginatorOptions.

Limitations

Stated plainly, so you can design around them rather than discover them mid-build.

• Not on npm yet. Install via a file: dependency (see Installation) — there is no npm install @frevvu/bot-sdk today.
• The message event doesn't exist. It's declared in the type union but never emitted. Use channels.watch().
• Everything is polled, nothing is pushed. The default 2-second interval means every bot action — a reply, a button's visible effect, a voice command — has up to ~2 seconds of latency baked in. Modals add a bit more on top of that (see Modals).
• No bot-wide message feed. You must explicitly watch() each channel a bot should react in — there's no single firehose event for "any message, anywhere."
• Reactions aren't visible to bots. There's no poll surface or event for emoji reactions today — only button clicks and select-menu choices reach a bot via the interaction event.
• E2EE key bootstrap needs a live member. See the callout in End-to-end encryption — always verify a real client can decrypt before depending on it.
• New encrypted messages are refused. channels.sendEncrypted() always throws — Frevvu's server stopped accepting new "e2ee" text messages (voice/video calls are unaffected). E2EE support today is read-only: decrypting a channel's older history.