Bot Controller

/**
 * Create a new Botkit instance and optionally specify a platform-specific adapter
 * @param config Configuration for this instance of Botkit
 */
constructor(config: BotkitConfiguration);

interface BotkitConfiguration {
  /** Path used to create incoming webhook URI. Defaults to `/api/messages` */
  webhook_uri?: string;
  /** Name of the dialogState property in the ConversationState. Defaults to `dialogState` */
  dialogStateProperty?: string;
  /** A fully configured BotBuilder Adapter */
  adapter?: any;
  /** Configuration passed to the adapter when created internally */
  adapterConfig?: { [key: string]: any };
  /** An instance of Express used to define web endpoints */
  webserver?: any;
  /** Array of middlewares automatically bound to the webserver */
  webserver_middlewares?: any[];
  /** A Storage interface compatible with BotBuilder specification */
  storage?: Storage;
  /** Disable webserver. Defaults to false */
  disable_webserver?: boolean;
  /** Disable messages normally sent to the console during startup */
  disable_console?: boolean;
  /** Limit of incoming JSON payloads. Defaults to '100kb' */
  jsonLimit?: string;
  /** Limit of incoming URL encoded payloads. Defaults to '100kb' */
  urlEncodedLimit?: string;
}

import { Botkit } from "botkit";

// Basic configuration
const controller = new Botkit({
  webhook_uri: "/api/messages",
});

// Advanced configuration with custom adapter
import { SlackAdapter } from "@botbuilder/adapter-slack";

const adapter = new SlackAdapter({
  botToken: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

const controller = new Botkit({
  adapter: adapter,
  storage: myCustomStorage,
  disable_console: true,
});

/**
 * Get a value from the configuration
 * @param key The name of a value stored in the configuration
 * @returns The value stored in the configuration (or null if absent)
 */
getConfig(key?: string): any;

// Get entire config object
const config = controller.getConfig();

// Get specific value
const webhookUri = controller.getConfig("webhook_uri");

/**
 * Load a plugin module and bind all included middlewares
 * @param plugin_or_function A plugin module or function that returns plugin definition
 */
usePlugin(plugin_or_function: ((botkit: Botkit) => BotkitPlugin) | BotkitPlugin): void;

/**
 * Extend Botkit's controller with new functionality
 * @param name name of plugin
 * @param extension an object containing methods
 */
addPluginExtension(name: string, extension: any): void;

/** Access plugin extension methods */
get plugins(): { [key: string]: any };

interface BotkitPlugin {
  name: string;
  middlewares?: { [key: string]: any[]; };
  init?: (botkit: Botkit) => void;
  [key: string]: any;
}

// Load a plugin
controller.usePlugin(myPlugin);

// Create and register plugin extension
const extension = {
  doSomething: () => { return "done"; }
};
controller.addPluginExtension("myExtension", extension);

// Use extension
controller.plugins.myExtension.doSomething();

/**
 * Load a Botkit feature module
 * @param p path to module file
 */
loadModule(p: string): void;

/**
 * Load all Botkit feature modules located in a given folder
 * @param p path to a folder of module files
 * @param exts the extensions that you would like to load (default: ['.js'])
 */
loadModules(p: string, exts?: string[]): void;

// Load single module
controller.loadModule("./features/greetings.js");

// Load all modules from folder
controller.ready(() => {
  controller.loadModules("./features");
});

/**
 * Expose a folder to the web as a set of static files
 * @param alias the public alias ie /myfiles
 * @param path the actual path
 */
publicFolder(alias: string, path: string): void;

/**
 * Convert a local path from a plugin folder to a full path relative to the webserver's main views folder
 * @param path_to_view path to view directory
 */
getLocalView(path_to_view: string): string;

// Serve static files
controller.publicFolder("/public/images", __dirname + "/images");

// Get view path for rendering
const viewPath = controller.getLocalView(path.join(__dirname, "views"));

/**
 * Add a dependency to Botkit's bootup process
 * @param name The name of the dependency that is being loaded
 */
addDep(name: string): void;

/**
 * Mark a bootup dependency as loaded and ready to use
 * @param name The name of the dependency that has completed loading
 */
completeDep(name: string): boolean;

/**
 * Execute function when Botkit is booted and ready to run
 * @param handler A function to run when Botkit is booted and ready
 */
ready(handler: () => any): void;

// Add dependency
controller.addDep("database");

// Mark dependency complete after async setup
setupDatabase().then(() => {
  controller.completeDep("database");
});

// Execute when ready
controller.ready(() => {
  console.log("Bot is ready!");
  controller.loadModules("./features");
});

/**
 * Process incoming messages and evaluate them for triggers
 * @param turnContext a TurnContext representing an incoming message
 */
handleTurn(turnContext: TurnContext): Promise<any>;

// Typically handled automatically by Botkit, but can be called directly
await controller.handleTurn(turnContext);

/**
 * Add a dialog to the bot's dialog set
 * @param dialog A BotBuilder Dialog object
 */
addDialog(dialog: Dialog): void;

/**
 * Bind a handler function to fire after any dialog ends
 * @param dialog A dialog or dialog ID
 * @param handler Function to run when dialog completes
 */
afterDialog(dialog: Dialog | string, handler: BotkitHandler): void;

// Add a dialog to the bot
const myDialog = new BotkitConversation("my_dialog", controller);
controller.addDialog(myDialog);

// Handle dialog completion
controller.afterDialog("my_dialog", async (bot, message) => {
  console.log("Dialog completed!");
  await bot.say("Thanks for completing the conversation!");
});

/**
 * Create a platform-specific BotWorker instance
 * @param config Preferably receives a DialogContext, though can also receive a TurnContext
 * @param adapter An optional reference to a specific adapter
 */
spawn(config?: any, custom_adapter?: BotAdapter): Promise<BotWorker>;

/**
 * Save the current conversation state pertaining to a given BotWorker's activities
 * @param bot a BotWorker instance created using controller.spawn()
 */
saveState(bot: BotWorker): Promise<void>;

// Spawn bot for proactive messaging
const bot = await controller.spawn();
bot.changeContext(savedReference);
await bot.say("Proactive message!");

// Save state manually if needed
await controller.saveState(bot);

/**
 * Shutdown the webserver and prepare to terminate the app
 */
shutdown(): Promise<void>;

// Handle graceful shutdown
process.on("SIGINT", async () => {
  console.log("Shutting down bot...");
  await controller.shutdown();
  process.exit(0);
});

// Listen for shutdown event
controller.on("shutdown", async () => {
  console.log("Bot is shutting down!");
  // Cleanup resources
});

class Botkit {
  /** The current version of Botkit Core */
  version: string;
  
  /** Middleware endpoints for plugins and features to extend Botkit */
  middleware: {
    spawn: Ware;
    ingest: Ware;
    send: Ware;
    receive: Ware;
    interpret: Ware;
  };
  
  /** A BotBuilder storage driver - defaults to MemoryStorage */
  storage: Storage;
  
  /** An Express webserver */
  webserver: any;
  
  /** A direct reference to the underlying HTTP server object */
  http: any;
  
  /** Any BotBuilder-compatible adapter */
  adapter: any;
  
  /** A BotBuilder DialogSet that serves as the top level dialog container */
  dialogSet: DialogSet;
  
  /** The path of the main Botkit SDK, used to generate relative paths */
  PATH: string;
}