botact.js
Botact enables developers to focus on writing reusable application logic instead of spending time building infrastructure.
Table of content
Install
via npm:
$ npm i botact -S
via yarn:
$ yarn add botact
Examples
express:
const express = const bodyParser = const Botact = const app = const bot = confirmation: processenvCONFIRMATION token: processenvTOKEN // User wrote command 'start'bot // User wrote message which contains 'car' or 'tesla'bot // User joined in the groupbotevent'group_join' { } // User wrote any messagebot // Parser request bodyapp // Bot's endpointapp // Start listen on 3000app
koa:
const Koa = const Router = const bodyParser = const Botact = const app = const router = const bot = confirmation: processenvCONFIRMATION token: processenvTOKEN framework: 'koa' // User wrote command 'start'bot // User wrote message which contains 'car' or 'tesla'bot // User joined in the groupbotevent'group_join' { } // User wrote any messagebot // Bot's endpointrouter // Parser request bodyapp// Connect routesapp // Start listen on 3000app
Botact API
Methods
Core
- constructor(settings)
- .api(method, settings)
- .execute(method, settings, callback)
- .reply(userId, message, attachment, keyboard)
- .listen(...args)
Actions
- .command(command, callback)
- .event(event, callback)
- .hears(command, callback)
- .on(type, callback)
- .use(callback)
Options
Upload helpers
Error Handling
↑
Botact API: Coreconstructor(settings)
Create bot.
Definition:
constructor settings:
Usage:
const Botact = const bot = confirmation: processenvCONFIRMATION token: processenvTOKEN
.api(method, settings)
Call API method (https://vk.com/dev/methods).
Definition:
async api method: string, // required options?: object, // api call parameters: Promise<any>; // Promise with response/error
Usage:
const data = await bot
.execute(method, settings, callback)
Call API by execute.
Definition:
async execute method: string, // required options?: object, // api call parameters callback?:
Usage:
bot
.reply(userId, message, attachment, keyboard)
Sends message to user
Definition:
async reply userId: number, message: string, // required, if attachment not setten attachment: string, // required, if message not setten keyboard: Object // optional: Promise<any> // Promise with response/error
Usage:
bot
.listen(...args)
Start listen.
Definition:
express:
listen req: any, // Express request, required res: any // Express response, required callback:
koa:
listen ctx: object, // Koa object, required callback:
Usage:
// expressbot // koabot
↑
Botact API: Actions.command(command, callback)
Add command w/ strict match.
Definition:
command command: string | string, callback:
Usage:
bot
.event(event, callback)
Add event handler .
Definition:
event event: string | string, callback:
Usage:
botevent'group_join'
.hears(command, callback)
Add command w/ match like RegEx.
Definition:
hears hear: string | RegExp | string | RegExp, callback:
Usage:
bot
.on(type, callback)
Add reserved callback.
Definition:
on type: string, callback:
Usage:
botbot
.use(callback)
Add middleware.
Definition:
use callback:
Usage:
bot bot
↑
Botact API: Options[getter] options
Get options.
botoptions// {// confirmation: '12345',// token: 'abcde...'// }
[setter] options
Set options.
botoptions = foo: 'bar' // {// confirmation: '12345',// token: 'abcde...',// foo: 'bar'// }
.deleteOptions(settings)
Delete keys settings.
Definition:
deleteOptions keys: string: Botact
Usage:
bot// {// foo: 'bar'// }
↑
Botact API: Upload helpers.uploadCover(file, settings)
Upload and save cover. See detailed settings here.
Definition:
async uploadCover filepath: string, // Path to file with cover settings?: object: Promise<any> // Promise with response/error
Usage:
await bot// {// images: [// {// url: "URL",// width: 1920,// height: 1080// },// [Object],// [Object],// [Object],// [Object]// ]// }
.uploadDocument(file, peer_id, type)
Uploads document to peer.
Definition:
async uploadDocument filepath: string, // Path to file peer_id: number, type: 'doc' | 'audio_message' // 'doc' by default: Promise<any>; // Promise with response/error
Usage:
await bot// {// response:// [{// id: 1234,// owner_id: 1234,// title: "",// ...// }]// }
.uploadPhoto(file, peer_id)
Uploads photo to peer.
Definition:
async uploadPhoto filepath: string, // Path to picture peer_id: number: Promise<any> // Promise with response/error
Usage:
await bot// {// id: 1234,// album_id: 1234,// owner_id: 1234,// ...// }
↑
Botact API: Error Handling.catch(handler)
Add catch handler for errors.
Default handler:
console
Usage:
// Handle all botact errors herebot bot
.throw(error)
Throw error.
Usage:
bot bot
.assert(value, message)
Helper method to throw an error similar to .throw() when !value.
bot bot
Botact Flow API
Usage
const bot = ... redis: true // enable redis flowTimeout: 20 // timeout for delete documents redisConfig: // redis config port: 1234
$ redis-server
Methods
- .addScene(name, ...callbacks)
- .joinScene(ctx, scene, session, step, now)
- .nextScene(ctx, body)
- .leaveScene(ctx)
Example
const bodyParser = const express = const Botact = const app = const bot = confirmation: processenvCONFIRMATION token: processenvTOKEN redis: true flowTimeout: 20 // document will be deleted after 20 secs redisConfig: host: '127.0.0.1' // default host for redis port: 8080 // custom port for redis bot bot appappapp
Botact Flow API: Methods
.addScene(name, ...callbacks)
Add scene.
Definition:
addScene name: string, ...args:
Usage:
bot
.joinScene(ctx, scene, session, step, now)
Enter scene.
Definition:
async joinScene ctx: object, scene: string, session?: object, // {} by default step?: number, // 0 by default instantly?: boolean // true by default: Promise<Botact>;
Usage:
bot
.nextScene(ctx, body)
Navigate scene.
Definition:
async nextScene ctx: object, session?: object, // {} by default: Promise<Botact>;
Usage:
bot
.leaveScene(ctx)
Leave scene.
Definition:
async leaveScene ctx: object: Promise<Botact>;
Usage:
bot
TypeScript
Botact includes TypeScript definitions.
Tests
via npm:
$ npm test
via yarn:
$ yarn test
License
MIT.