@mainframe/bot-sdk/README.md

# Mainframe JavaScript SDK for bots

This documentation only covers the JavaScript SDK, see the [Mainframe bots documentation](http://developer.mainframe.com/) for more information about creating Mainframe bots, and the [bots UI framework repository](https://github.com/thusfresh/bot-ui-js) for a complementary tool to create bot UIs.

- [Installation](#installation)
- [Example](#example)
- [Data types](#types)
- [API](#api)
  - [`createConfig`](#createconfig)
  - [`createContext`](#createcontext)
  - [`createRouter`](#createrouter)
  - [`createServer`](#createserver)
  - [`log`](#log)
  - [`startServer`](#startserver)
- [Usage](#usage)
  - [Basic usage](#basic-usage) - the easiest way to get started
  - [With custom route handlers](#adding-custom-route-handlers) - when you need custom routes
  - [Using an existing Koa app](#using-an-existing-koa-app) - giving you the flexibility to implement what you need
- [License](#license)

## Installation

```sh
npm install @mainframe/bot-sdk # npm
yarn add @mainframe/bot-sdk # Yarn
```

## Example

```js
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](https://flow.org/en/docs/types/):

```js
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](https://github.com/alexmingoia/koa-router#exp_module_koa-router--Router) implementing HTTP endpoints for the provided handlers.

### createServer

`createServer (handlers: Handlers, config: Config): koa$Application`

Creates a [Koa Application](http://koajs.com/#application) implementing HTTP endpoints for the provided handlers.

### log

`log (...args: Array<mixed>): void`

Logs using [debug](https://github.com/visionmedia/debug) with the `mainframe-bot` namespace.

### startServer

`startServer (handlers: Handlers, parameters?: PartialConfig): void`

Creates a [Koa Application](http://koajs.com/#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](http://koajs.com/) to handle routing the provided handlers to the corresponding [HTTP endpoints used by the Mainframe server](http://developer.mainframe.com/#bot-api).  
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:
```js
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`](types) 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`](http://koajs.com/#application).  
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:

```js
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`](https://github.com/alexmingoia/koa-router#exp_module_koa-router--Router).  
This function requires a [`BotContext`](#types) 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:

```js
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](LICENSE) file