Core Bot Management

/**
 * Main robot class that orchestrates all bot functionality
 * @param adapter - String adapter name (e.g., "Shell", "Campfire") or adapter instance
 * @param httpd - Enable HTTP server (default: true)
 * @param name - Robot name (default: "Hubot") 
 * @param alias - Robot alias for mentions (default: false)
 */
class Robot {
  constructor(adapter: string | Adapter, httpd?: boolean, name?: string, alias?: string | boolean);
  
  // Core properties
  name: string;
  brain: Brain;
  adapter: Adapter;
  logger: Logger;
  router: Router; // Express router when HTTP enabled
  commands: string[]; // Help command strings
  
  // Lifecycle management
  async run(): Promise<void>;
  shutdown(): void;
  
  // Message processing
  async receive(message: Message): Promise<void>;
  
  // Communication
  async send(envelope: Envelope, ...strings: string[]): Promise<void>;
  async reply(envelope: Envelope, ...strings: string[]): Promise<void>;
  async messageRoom(room: string, ...strings: string[]): Promise<void>;
  
  // Error handling
  error(callback: (error: Error, response?: Response) => void): void;
  
  // HTTP client
  http(url: string, options?: HttpOptions): HttpClient;
  
  // Utility methods
  helpCommands(): string[];
  respondPattern(regex: RegExp): RegExp;
  parseVersion(): string;
}

import { Robot } from "hubot";

// Create bot with Shell adapter for local development
const robot = new Robot("Shell", true, "DevBot", "!");

// Create bot with custom adapter instance
import MyAdapter from "./my-adapter.js";
const adapter = new MyAdapter();
const robot = new Robot(adapter, false, "ProdBot");

// Start the bot
await robot.run();

// Graceful shutdown
process.on('SIGTERM', () => {
  robot.shutdown();
});

/**
 * Factory function to create Robot instances
 * @param adapter - Adapter name or instance
 * @param enableHttpd - Enable HTTP server
 * @param name - Robot name
 * @param alias - Robot alias
 * @returns Configured Robot instance
 */
function loadBot(adapter: string | Adapter, enableHttpd: boolean, name: string, alias: string): Robot;

import { loadBot } from "hubot";

const robot = loadBot("Shell", true, "MyBot", "!");
await robot.run();

/**
 * Start the robot and initialize adapter
 * Loads default scripts, starts HTTP server (if enabled), and runs adapter
 */
async run(): Promise<void>;

/**
 * Gracefully shutdown the robot
 * Closes adapter connection and HTTP server
 */
shutdown(): void;

/**
 * Load a single script file
 * @param filepath - Full path to script file
 * @param filename - Name of the file for logging
 */
async loadFile(filepath: string, filename: string): Promise<any>;

/**
 * Load all scripts from a directory
 * @param path - Directory path containing scripts
 */
async load(path: string): Promise<any[]>;

/**
 * Load external scripts from npm packages
 * @param packages - Array of npm package names or object with package configs
 */
async loadExternalScripts(packages: string[] | object): Promise<void>;

// Load individual script
await robot.loadFile("/path/to/my-script.js", "my-script.js");

// Load all scripts from directory
await robot.load("./scripts");

// Load external npm packages
await robot.loadExternalScripts([
  "hubot-help",
  "hubot-diagnostics",
  "@hubot-friends/hubot-pugme"
]);

// Access Express router for custom endpoints
robot.router.get("/status", (req, res) => {
  res.json({ status: "running", name: robot.name });
});

// HTTP server is automatically started with robot.run()
// Available at process.env.PORT or 8080

/**
 * Load and initialize adapter from path or built-in name
 * @param adapterPath - Path to adapter or built-in name
 */
async loadAdapter(adapterPath: string): Promise<void>;

/**
 * Process incoming message through middleware and listeners
 * @param message - Message instance to process
 * @returns Array of results from matching listeners
 */
async receive(message: Message): Promise<any[]>;

/**
 * Send messages to a specific room
 * @param room - Room identifier
 * @param strings - Messages to send
 */
async messageRoom(room: string, ...strings: string[]): Promise<void>;

/**
 * Send messages via adapter
 * @param envelope - Message envelope with user/room info
 * @param strings - Messages to send
 */
async send(envelope: Envelope, ...strings: string[]): Promise<void>;

/**
 * Reply to messages via adapter
 * @param envelope - Message envelope with user/room info  
 * @param strings - Reply messages
 */
async reply(envelope: Envelope, ...strings: string[]): Promise<void>;

// Register event listeners  
robot.on('error', (error) => {
  console.error('Robot error:', error);
});

robot.on('running', () => {
  console.log('Robot is now running');
});

robot.on('listening', (server) => {
  console.log('HTTP server started');
});

// Emit custom events
robot.emit('custom-event', data);

interface Robot {
  name: string;
  events: EventEmitter;
  brain: Brain;
  alias: string | boolean;
  adapter: Adapter;
  adapterName: string;
  commands: string[];
  listeners: Listener[];
  middleware: {
    listener: Middleware;
    response: Middleware;
    receive: Middleware;
  };
  logger: Logger;
  version: string;
  router?: Router;
  server?: Server;
}