Mainframe JavaScript SDK for bots
This documentation only covers the JavaScript SDK, see the Mainframe bots documentation for more information about creating Mainframe bots, and the bots UI framework repository for a complementary tool to create bot UIs.
- Installation
- Example
- Data types
- API
-
Usage
- Basic usage - the easiest way to get started
- With custom route handlers - when you need custom routes
- Using an existing Koa app - giving you the flexibility to implement what you need
- License
Installation
npm install @mainframe/bot-sdk # npm
yarn add @mainframe/bot-sdk # Yarn
Example
const { startServer } = require('@mainframe/bot-sdk')
startServer(
{
conversation_added({ conversation_id }, { sendMessage }) {
sendMessage({ conversation_id, message: 'Hello world' })
},
},
{
mainframe_secret: '<my bot secret>',
port: 3000,
},
)
Types
The SDK uses the following Flow types:
type PartialConfig = {
+mainframe_secret?: string,
+mainframe_url?: string,
+port?: number,
}
type Config = {|
+mainframe_secret: string,
+mainframe_url: string,
+port: number,
|}
type ServerContext = {|
+user_id: string,
+conversation_id?: string,
+subscription_id?: string,
+subscription_token?: string,
|}
type PostPayload = {|
+data: Object,
+context: ServerContext,
|}
type SendMessagePayload = {
conversation_id: string,
message?: string,
data?: Object,
}
type SubscriptionResponse = {|
+subscription_id: string,
|}
type BotContext = {|
+config: Config,
+callMainframe: (endpoint: string, data?: Object) => Promise<void | Object>,
+sendMessage: (payload: SendMessagePayload) => Promise<void>,
+setupSubscription: (payload: {
subscription_token: string,
label: string,
}) => Promise<SubscriptionResponse>,
+editSubscription: (payload: {
subscription_token: string,
label?: string,
}) => Promise<SubscriptionResponse>,
|}
type BotResponse = {|
success: boolean,
message?: string,
data?: Object,
|}
type Handlers = {|
+enable?: (payload: { user_id: string }, context: BotContext) => void,
+disable?: (payload: { user_id: string }, context: BotContext) => void,
+conversation_added?: (
payload: {|
+user_id: string,
+conversation_id: string,
|},
context: BotContext,
) => void,
+conversation_removed?: (
payload: {|
+user_id: string,
+conversation_id: string,
|},
context: BotContext,
) => void,
+edit_subscription?: (
payload: {|
+user_id: string,
+conversation_id: string,
+subscription_id: string,
|},
context: BotContext,
) => void,
+delete_subscription?: (
payload: {|
+subscription_id: string,
|},
context: BotContext,
) => void,
+mention?: (
payload: {|
+user_id: string,
+conversation_id: string,
+text: string,
|},
context: BotContext,
) => void,
+post?: (
payload: PostPayload,
context: BotContext,
) => BotResponse | Promise<BotResponse>,
+preview?: (
payload: {|
+user_id: string,
+link: string,
|},
context: BotContext,
) => BotResponse | Promise<BotResponse>,
|}
API
createConfig
createConfig (parameters?: PartialConfig): Config
Creates the configuration using the provided parameters, environment variables or defaults.
createContext
createContext (config: Config): BotContext
Creates a bot context provided to the handlers, notably to allow to communicate with Mainframe.
createRouter
createRouter (handlers: Handlers, context: BotContext): Router
Creates a Koa Router implementing HTTP endpoints for the provided handlers.
createServer
createServer (handlers: Handlers, config: Config): koa$Application
Creates a Koa Application implementing HTTP endpoints for the provided handlers.
log
log (...args: Array<mixed>): void
Logs using debug with the mainframe-bot
namespace.
startServer
startServer (handlers: Handlers, parameters?: PartialConfig): void
Creates a Koa Application implementing HTTP endpoints for the provided handlers and start listening using the port
provided in parameters
, defaulting to 4000
.
Usage
Basic usage
This SDK uses the Koa framework to handle routing the provided handlers to the corresponding HTTP endpoints used by the Mainframe server.
All of these handlers are optional by default and you'll only need to implement them according to the needs of your bot.
The simplest way to get started it to call startServer(handlers)
, for example:
const { startServer } = require('@mainframe/bot-sdk')
startServer({
conversation_added(payload, context) {
context.sendMessage({
conversation_id: payload.conversation_id,
message: 'Hello world',
})
},
})
All handlers will be called with two arguments: an Object containing the request payload, and the BotContext
notably allowing to make requests to Mainframe.
startServer()
also supports providing a configuration Object as second argument, used to create the context. When not provided, the configuration will use the environment variables MAINFRAME_SECRET
, MAINFRAME_URL
and PORT
.
The configuration will by default use https://api.mainframe.com/bots/v1
as Mainframe's API URL and listen on port 4000
.
Your bot's secret
must be provided, either directly as mainframe_secret
in the configuration object, or in the MAINFRAME_SECRET
environment variable.
Adding custom route handlers
For more advanced use cases, you may want to create the Koa application without listening right-away, this is possible using the createServer(handlers, config)
function, that will return an Application instance
.
This function expects a config
Object providing all the configuration values. If you want to automatically use the environment variables or default configuration values, you can use createConfig(optionalConfig)
that will use the values provided in optionalConfig
, or default to the environment variables or predefined values.
Example:
const { createConfig, createServer, log } = require('@mainframe/bot-sdk')
const config = createConfig({ mainframe_secret: '<your bot secret>' })
const server = createServer(
{
enable(payload) {
log('enabled by user %s', payload.user_id)
},
},
config,
)
server.use(ctx => {
ctx.body = 'Hello'
})
server.listen(3000)
Using an existing Koa app
If you are already using Koa and want to integrate the bot API with even more control, you can do so by using the createRouter(handlers, context)
, that will return a Router instance
.
This function requires a BotContext
to be provided as the second argument, that will be injected to the handlers when called. You can provide a custom implementation of the context
if you have specific needs, or use createContext(config)
to create it.
Example:
const { createConfig, createContext, createRouter, log } = require('@mainframe/bot-sdk')
const Koa = require('koa')
const app = new Koa()
const config = createConfig() // Will use MAINFRAME_SECRET from the environment
const context = createContext(config)
const api = createRouter(
{
enable(payload) {
log('enabled by user %s', payload.user_id)
},
},
context,
)
app.use(api.routes())
app.listen(3000)
License
MIT
See LICENSE file