botsilo

MQTT bot primitives for direct messaging, broadcasts, and tag channels under a per-user namespace.

What it does

• Bot class (bot.js) connects with persistent sessions (MQTT 5 + max session expiry) and subscribes to <username>/broadcast/#, <username>/send/<clientId>/#, and any followed tag topics.
• Emits connect, offline, error, message ({ payload, from }), broadcast ({ payload, from }), and tag ({ payload, tag, from }). Payloads are normalized objects: { type: 'text' | 'json', content, timestamp } plus optional tags/mentions arrays on text payloads.
• Helpers: bot.send(targetId, data), bot.broadcast(data), bot.publishTag(tag, data), bot.follow(tag). Send/broadcast/tag calls auto-wrap strings into { type: 'text' } payloads (auto-extracting tags and mentions, and stripping them from the content) and objects into { type: 'json' } payloads, adding a timestamp. Broadcasts fan-out #tags to tag topics and @mentions to direct topics when the original data is a string.
• Demos: interactive CLI (botsilo bin) that connects a bot and broadcasts what you type.

Prereqs

• Node.js 18+ (uses the built-in test runner and modern syntax).
• MQTT broker reachable at mqtt://localhost:1883.
  • Create user credentials (defaults in tests are gg / gg).

Install

• Library: npm install botsilo
• Root (bots, CLI, tests): npm install

Using the Bot class

import Bot from 'botsilo';

const botA = new Bot({
  host: 'mqtt://localhost:1883',
  username: 'user',
  password: 'pass',
  clientId: 'bot-a',
});
const botB = new Bot({
  host: 'mqtt://localhost:1883',
  username: 'user',
  password: 'pass',
  clientId: 'bot-b',
});

botA.on('connect', () => console.log('bot-a connected'));
botA.on('message', ({ payload, from }) => console.log('direct from', from, payload.content));
botA.on('broadcast', ({ payload, from }) => console.log('broadcast from', from, payload.content));
botA.on('tag', ({ payload, tag, from }) => console.log(`tag ${tag} from ${from}:`, payload.content));

botA.start();
botB.start();

botA.send(botB.clientId, 'hello bot-b');
botA.broadcast('hello all bots #updates @bot-b'); // fans out to the tag and mention topics too
await Promise.all([botA.follow('updates'), botB.follow('updates')]);
botA.publishTag('news', { headline: 'Botsilo ships formatted payloads' });

CLI client (botsilo)

Interactive REPL that connects a single bot and broadcasts each line you type. Run via npx botsilo (or botsilo if installed globally):

npx botsilo --username gg --clientId bot-a --password gg \
  [--host mqtt://localhost:1883] [--mqttOptions '{"protocolVersion":5}']

Type exit/quit to disconnect. Broadcasts carry #tags and @mentions to the appropriate tag/direct topics automatically.