0
# Hubot
1

2
Hubot is a comprehensive chat bot framework modeled after GitHub's Campfire bot, designed to enable developers to build extensible chat bots that can work across multiple chat services including Slack, Discord, MS Teams, and IRC. The framework provides a robust library with built-in support for custom scripts, adapters for various chat platforms, command-line interface for creating and managing bot instances, and Express.js-powered HTTP server capabilities.
3

4
## Package Information
5

6
- **Package Name**: hubot
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install hubot`
10

11
## Core Imports
12

13
```javascript
14
import { Robot, Adapter, loadBot } from "hubot";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Robot, Adapter, loadBot } = require("hubot");
21
```
22

23
Complete imports (all available exports):
24

25
```javascript
26
import { 
27
  Robot, 
28
  Adapter, 
29
  User, 
30
  Brain, 
31
  Response, 
32
  Listener, 
33
  TextListener,
34
  Message,
35
  TextMessage,
36
  EnterMessage,
37
  LeaveMessage,
38
  TopicMessage,
39
  CatchAllMessage,
40
  DataStore,
41
  DataStoreUnavailable,
42
  Middleware,
43
  loadBot
44
} from "hubot";
45
```
46

47
## Basic Usage
48

49
```javascript
50
import { Robot } from "hubot";
51

52
// Create a bot with Shell adapter for development
53
const robot = new Robot("Shell", true, "MyBot");
54

55
// Listen for messages
56
robot.hear(/hello/i, (res) => {
57
  res.reply("Hello there!");
58
});
59

60
// Respond to direct mentions
61
robot.respond(/how are you/i, (res) => {
62
  res.send("I'm doing great, thanks for asking!");
63
});
64

65
// Listen for user events
66
robot.enter((res) => {
67
  res.send(`Welcome, ${res.message.user.name}!`);
68
});
69

70
// Start the bot
71
await robot.run();
72
```
73

74
## Architecture
75

76
Hubot is built around several key components:
77

78
- **Robot**: Central orchestrator managing adapters, listeners, brain, HTTP server, and event system
79
- **Adapters**: Interface between the bot and chat services (Shell, Campfire, etc.)
80
- **Brain**: Memory and user management system with persistent storage and automatic serialization
81
- **Listeners**: Pattern-matching system for messages and events with middleware support
82
- **Messages**: Type hierarchy for different chat events (text, enter/leave, topic changes, catch-all)
83
- **Middleware**: Pluggable request/response processing pipeline with listener, response, and receive phases
84
- **Scripts**: Dynamically loaded bot functionality from local files or npm packages
85
- **DataStore**: Pluggable persistent storage system for robot data
86
- **HTTP Server**: Built-in Express.js server for webhooks and web interfaces
87
- **Event System**: EventEmitter-based communication between components
88

89
## Capabilities
90

91
### Core Bot Management
92

93
Primary robot functionality including lifecycle management, message processing, and adapter integration. Essential for all bot implementations.
94

95
```javascript { .api }
96
class Robot {
97
  constructor(adapter: string | Adapter, httpd?: boolean, name?: string, alias?: string | boolean);
98
  async run(): Promise<void>;
99
  shutdown(): void;
100
  async messageRoom(room: string, ...strings: string[]): Promise<void>;
101
  helpCommands(): string[];
102
  parseVersion(): string;
103
  respondPattern(regex: RegExp): RegExp;
104
}
105

106
function loadBot(adapter: string | Adapter, enableHttpd: boolean, name: string, alias?: string | boolean): Robot;
107
```
108

109
[Core Bot Management](./core-bot-management.md)
110

111
### Message Handling
112

113
Comprehensive message pattern matching and response system for different types of chat interactions and events.
114

115
```javascript { .api }
116
// Listener registration methods
117
hear(regex: RegExp, options?: ListenerOptions, callback: ListenerCallback): void;
118
respond(regex: RegExp, options?: ListenerOptions, callback: ListenerCallback): void;
119
enter(options?: ListenerOptions, callback: ListenerCallback): void;
120
leave(options?: ListenerOptions, callback: ListenerCallback): void;
121
topic(options?: ListenerOptions, callback: ListenerCallback): void;
122
catchAll(options?: ListenerOptions, callback: ListenerCallback): void;
123
listen(matcher: Function, options?: ListenerOptions, callback: ListenerCallback): void;
124
error(callback: (error: Error, response?: Response) => void): void;
125

126
// Response methods
127
class Response {
128
  async send(...strings: string[]): Promise<void>;
129
  async reply(...strings: string[]): Promise<void>;
130
  async emote(...strings: string[]): Promise<void>;
131
  async topic(...strings: string[]): Promise<void>;
132
  async play(...strings: string[]): Promise<void>;
133
  async locked(...strings: string[]): Promise<void>;
134
  random(items: any[]): any;
135
  finish(): void;
136
  http(url: string, options?: object): HttpClient;
137
}
138
```
139

140
[Message Handling](./message-handling.md)
141

142
### Brain and User Management
143

144
Robot memory system with user management, persistent data storage, and automatic serialization for maintaining state across restarts.
145

146
```javascript { .api }
147
class Brain {
148
  set(key: string, value: any): Brain;
149
  get(key: string): any;
150
  remove(key: string): Brain;
151
  save(): void;
152
  close(): void;
153
  setAutoSave(enabled: boolean): void;
154
  resetSaveInterval(seconds: number): void;
155
  mergeData(data: object): void;
156
  users(): Record<string, User>;
157
  userForId(id: string, options?: UserOptions): User;
158
  userForName(name: string): User | null;
159
  usersForRawFuzzyName(fuzzyName: string): User[];
160
  usersForFuzzyName(fuzzyName: string): User[];
161
}
162

163
class User {
164
  constructor(id: string, options?: UserOptions);
165
  async set(key: string, value: any): Promise<void>;
166
  async get(key: string): Promise<any>;
167
}
168
```
169

170
[Brain and User Management](./brain-user-management.md)
171

172
### Adapters and Integration
173

174
Adapter system for integrating with different chat platforms, including built-in Shell and Campfire adapters and extensibility patterns.
175

176
```javascript { .api }
177
class Adapter {
178
  constructor(robot: Robot);
179
  async send(envelope: Envelope, ...strings: string[]): Promise<void>;
180
  async emote(envelope: Envelope, ...strings: string[]): Promise<void>;
181
  async reply(envelope: Envelope, ...strings: string[]): Promise<void>;
182
  async topic(envelope: Envelope, ...strings: string[]): Promise<void>;
183
  async play(envelope: Envelope, ...strings: string[]): Promise<void>;
184
  async run(): Promise<void>;
185
  close(): void;
186
  async receive(message: Message): Promise<void>;
187
}
188
```
189

190
[Adapters and Integration](./adapters-integration.md)
191

192
### Script and Middleware System
193

194
Dynamic script loading from files and npm packages, plus middleware system for customizing message processing pipeline.
195

196
```javascript { .api }
197
// Script loading
198
async loadFile(filepath: string, filename: string): Promise<any>;
199
async load(path: string): Promise<any[]>;
200
async loadExternalScripts(packages: string[] | object): Promise<void>;
201
async loadAdapter(adapterPath?: string): Promise<void>;
202

203
// Middleware registration
204
listenerMiddleware(middleware: MiddlewareFunction): void;
205
responseMiddleware(middleware: MiddlewareFunction): void;
206
receiveMiddleware(middleware: MiddlewareFunction): void;
207

208
class Middleware {
209
  constructor(robot: Robot);
210
  register(middleware: MiddlewareFunction): void;
211
  async execute(context: object): Promise<boolean>;
212
}
213
```
214

215
[Scripts and Middleware](./scripts-middleware.md)
216

217
### Command Line Interface
218

219
Complete CLI for creating, configuring, and running hubot instances with various adapter and configuration options.
220

221
```bash { .api }
222
# Create new bot deployment
223
hubot --create mybot --adapter @hubot-friends/hubot-slack
224

225
# Run bot with options
226
hubot --adapter Shell --name MyBot --alias "!"
227

228
# Configuration testing
229
hubot --config-check
230
```
231

232
[Command Line Interface](./cli.md)
233

234
### Data Persistence
235

236
Pluggable data storage system providing persistent storage for robot data with support for custom backend implementations.
237

238
```javascript { .api }
239
class DataStore {
240
  constructor(robot: Robot);
241
  async set(key: string, value: any): Promise<void>;
242
  async setObject(key: string, objectKey: string, value: any): Promise<void>;
243
  async setArray(key: string, value: any): Promise<void>;
244
  async get(key: string): Promise<any>;
245
  async getObject(key: string, objectKey: string): Promise<any>;
246
}
247

248
class DataStoreUnavailable extends Error {}
249
```
250

251
[Data Persistence](./datastore.md)
252

253
## Types
254

255
```javascript { .api }
256
interface ListenerOptions {
257
  id?: string;
258
}
259

260
interface UserOptions {
261
  name?: string;
262
  room?: string;
263
  [key: string]: any;
264
}
265

266
interface Envelope {
267
  room: string;
268
  user: User;
269
  message: Message;
270
}
271

272
interface HttpClient {
273
  get(): Promise<any>;
274
  post(data?: any): Promise<any>;
275
  put(data?: any): Promise<any>;
276
  delete(): Promise<any>;
277
  patch(data?: any): Promise<any>;
278
  head(): Promise<any>;
279
  header(name: string, value: string): HttpClient;
280
  headers(headers: object): HttpClient;
281
  query(params: object): HttpClient;
282
  timeout(ms: number): HttpClient;
283
  auth(user: string, pass: string): HttpClient;
284
  encoding(encoding: string): HttpClient;
285
}
286

287
abstract class Message {
288
  constructor(user: User, done?: boolean);
289
  finish(): void;
290
  user: User;
291
  done: boolean;
292
  room?: string;
293
}
294

295
class TextMessage extends Message {
296
  constructor(user: User, text: string, id?: string);
297
  match(regex: RegExp): RegExpMatchArray | null;
298
  toString(): string;
299
  text: string;
300
  id?: string;
301
}
302

303
class EnterMessage extends Message {}
304
class LeaveMessage extends Message {}
305
class TopicMessage extends TextMessage {}
306
class CatchAllMessage extends Message {
307
  constructor(message: Message);
308
  message: Message;
309
}
310

311
type ListenerCallback = (response: Response) => void | Promise<void>;
312
type MiddlewareFunction = (context: any, next: () => void, done: () => void) => void;
313
```