@mainframe/bot-sdk/README.md

# Mainframe JavaScript SDK for bots

Work in progress

## 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 ClientContext = {|
  +user: {
    +id: string,
    +username: string,
    +name: string,
  },
  +conversation?: {
    +id: string,
    +subject: ?string,
    +type: 'bot' | 'direct' | 'default' | 'space',
  },
  +organization?: {
    +id: string,
    +username: string,
    +name: string,
  },
  +subscription_token?: string,
|}

type PostPayload = {|
  +user_id: string,
  +data: Object,
  +context: ClientContext,
|}

type BotContext = {|
  +config: Config,
  +callMainframe: (endpoint: string, data?: Object) => Promise<void | Object>,
  +sendEvent: (payload: {
    conversation_id: string,
    message?: string,
    data?: Object,
  }) => Promise<void>,
|}

type BotResponse = {|
  success: boolean,
  message?: string,
  data?: Object,
|}

type Handlers = {|
  enable?: (payload: { user_id: string }) => void,
  disable?: (payload: { user_id: string }) => void,
  conversation_added?: (payload: {
    user_id: string,
    conversation_id: string,
  }) => void,
  conversation_removed?: (payload: {
    user_id: string,
    conversation_id: string,
  }) => void,
  edit_subscription?: (payload: {
    user_id: string,
    conversation_id: string,
    subscription_id: string,
  }) => void,
  delete_subscription?: (payload: { subscription_id: string }) => void,
  post?: (payload: PostRequest) => 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): express$Router`

Creates an [Express Router](https://expressjs.com/en/4x/api.html#router) implementing HTTP endpoints for the provided handlers.

### createServer

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

Creates an [Express Application](https://expressjs.com/en/4x/api.html#app) 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 an [Express Application](https://expressjs.com/en/4x/api.html#app) implementing HTTP endpoints for the provided handlers and start listening using the `port` provided in `parameters`, defaulting to `4000`.

## License

MIT  
See [LICENSE file](LICENSE)