# Rave SDK for Node.js TypeScript/Node.js SDK for the Rave app - A WebSocket bot library for managing multiple chat channels independently. ## Features - **Independent WebSocket Connections**: Each chat channel runs with its own WebSocket connection, completely isolated from others - **Kick Handling**: Automatically detects when a bot is kicked and prevents reconnection attempts - **User Join/Leave Detection**: Tracks user state changes by comparing state messages - **Message ID Tracking**: Stores message IDs to properly match replies to original messages - **Multi-Mesh Management**: Automatically manages multiple bot instances across different meshes - **Command System**: Discord-like command system with custom prefixes - **Event System**: Comprehensive event handling for user joins, leaves, messages, and more ## Installation ```bash pnpm install pnpm build ``` ## Quick Start ### Simple Single Bot ```typescript import { RaveBot } from 'ravesdk-js'; const bot = new RaveBot( "server.com", "room-id", "peer-id", "auth-token", "device-id", "!", // command prefix false // debug ); bot.command("hello", async (ctx) => { await ctx.reply("Hello! 👋"); }); await bot.run(); ``` ### Multi-Mesh Bot Manager ```typescript import { BotManager, RaveAPIClient } from 'ravesdk-js'; const manager = new BotManager( "device-id", "peer-id", "auth-token", "!", // command prefix false, // debug new RaveAPIClient("auth-token"), 10, // max retries 1.0, // initial backoff 60.0, // max backoff 60.0, // discovery interval "invited" // mesh mode ); manager.command("hello", async (ctx) => { await ctx.reply("Hello from all meshes!"); }); manager.event("on_user_join", async (bot, userInfo) => { await bot.sendMessage(`Welcome ${userInfo.displayName}!`); }); await manager.run(20, "en"); ``` ## Key Features ### Independent WebSocket Connections Each bot instance creates its own WebSocket connection. This ensures that: - Connection issues in one mesh don't affect others - Each connection manages its own ping loop and message queue - No shared state between bot instances ### Kick Handling When a bot receives a "kicked" notification: - The bot is marked as kicked - The WebSocket connection is closed - No reconnection attempts are made - The bot is removed from the manager's registry ### User Join/Leave Detection The bot tracks user state by: 1. Initializing user list from mesh info API on connect 2. Comparing subsequent state messages to detect changes 3. Firing `on_user_join` and `on_user_left` events when users join or leave ### Message ID Tracking The bot tracks all sent message IDs to: - Match replies to original messages - Detect when users reply to bot messages - Handle cases where server assigns different IDs ## API Reference ### RaveBot Main bot class for managing a single mesh connection. **Constructor:** ```typescript new RaveBot( server: string, roomId: string, peerId: string, authToken?: string, deviceId?: string, commandPrefix?: string | string[], debug?: boolean ) ``` **Methods:** - `command(name, handler)` - Register a command handler - `event(name, handler)` - Register an event handler - `sendMessage(text, replyTo?, media?)` - Send a chat message - `run()` - Start the bot **Events:** - `on_connected` - Fired when bot connects - `on_user_join` - Fired when a user joins - `on_user_left` - Fired when a user leaves - `on_message` - Fired when a message is received - `on_kicked` - Fired when bot is kicked ### BotManager Manages multiple bot instances across different meshes. **Constructor:** ```typescript new BotManager( deviceId: string, peerId: string, authToken?: string, commandPrefix?: string | string[], debug?: boolean, apiClient?: RaveAPIClient, maxRetries?: number, retryInitialBackoff?: number, retryMaxBackoff?: number, discoveryInterval?: number, meshMode?: "invited" | "all" ) ``` **Methods:** - `command(name, handler)` - Register a global command - `event(name, handler)` - Register a global event handler - `start(limit?, lang?)` - Start the manager - `stop()` - Stop all bots - `run(limit?, lang?)` - Start and wait until stopped - `getStatus()` - Get status of all bots ## Examples See the `examples/` directory for more examples: - `simple-bot.ts` - Single bot example - `multi-mesh-bot.ts` - Multi-mesh bot manager example - `commands-example.ts` - Custom commands example ## Migration from Python This Node.js library is a direct port of the Python `ravesdk` library. Key differences: 1. **Async/Await**: Uses Promises instead of Python's asyncio 2. **TypeScript**: Full type safety with TypeScript 3. **Event Loop**: Uses Node.js event loop instead of asyncio 4. **WebSocket Library**: Uses `ws` instead of `websockets` The API is designed to be as similar as possible to the Python version for easy migration. ## License MIT # ravejs