bonktools

Getting started

Installation and first bot

Install the package, authenticate and bring up your first room.

Requirements

  • Node.js 20.18.1 or newer.
  • A bonk.io account (recommended for 24/7 rooms).
  • The package is ESM ("type": "module"); a CommonJS build is also provided.

Installation

bash
npm install bonktools
# or: pnpm add bonktools · yarn add bonktools

The package brings its dependencies (socket.io-client, werift, ws, pino, zod, undici, eventemitter3) and ships the TypeScript types.

Authentication

The library supports two modes:

ts
import type { AuthOptions } from 'bonktools';

// Registered account (recommended for 24/7)
const auth: AuthOptions = { type: 'registered', username: 'my_user', password: 'my_password' };

// Guest (no HTTP authentication call)
const guest: AuthOptions = { type: 'guest', guestName: 'BonkBot' };

With type: 'registered', the library calls bonk2.io/scripts/login_legacy.php and reuses the token across every room of the same session.

Your first bot

Create bot.ts:

ts
import { createRoom } from 'bonktools';

const room = await createRoom({
  auth: { type: 'registered', username: process.env.BONK_USER!, password: process.env.BONK_PASS! },
  desiredState: { roomName: 'Hello, bonk!', password: '', maxPlayers: 6, mode: 'b', rounds: 3 },
});

console.log('Room link:', room.shareLink);

room.on('player-join', (p) => room.chat(`Welcome, ${p.userName}!`));
room.on('chat-message', ({ message }) => {
  if (message === '!ping') room.chat('Pong!');
});

Run it:

bash
BONK_USER=your_user BONK_PASS=your_password npx tsx bot.ts

createRoom() only resolves after the server confirms the room, so room.shareLink is already available.

What next?