@mainframe/bot-sdk

This package has been deprecated


License
MIT
Install
npm install @mainframe/bot-sdk@0.1.2

Documentation

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

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