Skip to content

GitLab

Commit 07824b9f authored by Tim Kinnane's avatar Tim Kinnane
Browse files

docs(readme): Init project documentation

parent 67f7d03a
Hide whitespace changes
Inline Side-by-side
Showing with 380 additions and 77 deletions
README.md
View file @ 07824b9f
# rocketchat-bot-driver
Agnostic interface for bot adaptors to interact with Rocket.Chat
[asteroid]: https://www.npmjs.com/package/asteroid
### WORK IN PROGRESS
\ No newline at end of file
# Rocket.Chat Bot Driver
An agnostic interface for bot adaptors to interact with Rocket.Chat
## Overview
Rocket.Chat makes it easy for bot makers to provide the best solutions and
experience for their community. The internal Hubot and adapter enables chat-ops
workflows and multi-channel, multi-user, public and private interactions.
This package provides the core interface to subscribe to message streams, send
messages and query user details.
We have more bot features and adapters on the roadmap and encourage the
community to implement this driver to provide adapters for their bot framework
or platform of choice.
## API
See full API documentation links in the generated docs. Below is just a summary:
---
### `driver.connect(options, cb?)`
- Options accepts `host` and `timeout`
- Returns an [asteroid][asteroid] instance
- Can return a promise, or use error-first callback pattern
See [Asteroid][asteroid] docs for methods that can be called from that API.
---
## Getting Started
A local instance of Rocket.Chat is required for unit tests to confirm connection
and subscription methods are functional. And it helps to manually run your bot
interactions locally while in development.
## Use as Dependency
`yarn add rocketchat-bot-driver` or `npm install --save rocketchat-bot-driver`
ES6 Module, using async
```
import { driver } from 'rocketchat-bot-driver'
const asteroid = await driver.connect({ host: 'localhost:3000' })
```
More to come...
## Develop & Test
### Settings
| Env var | Description |
| --------------------- | ---------------------------------------------------- |
| `ROCKETCHAT_URL` | URL of the Rocket.Chat to connect to |
| `ADMIN_USERNAME` | Admin user password for API |
| `ADMIN_PASS` | Admin user password for API |
| `ROCKETCHAT_USER` | Bot password for tests |
| `ROCKETCHAT_PASS` | Bot username for tests |
These are only required in test and development, assuming in production they
will be passed from the adapter implementing this package.
If a `.env` file exists in the project folder, it will be used by `dotenv`.
### Installing Rocket.Chat
Clone and run a new instance of Rocket.Chat locally, using either the internal
mongo or a dedicated local mongo for testing, so the bot can't affect any other
Rocket.Chat development you might do locally.
The following will provision a default admin user on build, so it can be used to
access the API, allowing bot driver utils to prepare for and clean up tests.
- `git clone https://github.com/RocketChat/Rocket.Chat.git rc-bot-test`
- `cd rc-bot-test`
- `meteor npm install`
- `export ADMIN_PASS=pass; export ADMIN_USERNAME=admin; export MONGO_URL='mongodb://localhost:27017/rc-bot-test'; meteor`
Using `yarn` to run local tests and build scripts is recommended.
Do `npm install -g yarn` if you don't have it. Then setup the project:
- `git clone https://github.com/RocketChat/rocketchat-bot-driver`
- `cd rocketchat-bot-driver`
- `yarn`
### Test Scripts
- `yarn test` runs tests and coverage locally
- `yarn test:debug` runs tests without coverage, breaking for debug attach
- `yarn docs` generates docs
- `yarn build` runs tests, coverage, compiles and generates docs
`yarn:hook` is run on git push hooks to prevent publishing with failing tests.
### Integration Tests
The node scripts in `utils` are used to prepare for and clean up after test
interactions. They use the Rocket.Chat API to create a bot user and a mock human
user (benny) for the bot to interact with. They *should* restore the pre-test
state but it is always advised to only run tests with a connection to a clean
local instance of Rocket.Chat.
### Debugging
Configs are included in source for VS Code using Wallaby or Mocha Sidebar.
coverage/lcov.info
View file @ 07824b9f
......@@ -12,12 +12,12 @@ BRH:0
end_of_record
TN:
SF:/Volumes/x/code/rocketchat-bot-driver/src/lib/driver.ts
FN:62,connect
FN:63,(anonymous_3)
FN:70,(anonymous_4)
FN:71,(anonymous_5)
FN:73,(anonymous_6)
FN:80,(anonymous_7)
FN:61,connect
FN:62,(anonymous_3)
FN:69,(anonymous_4)
FN:70,(anonymous_5)
FN:72,(anonymous_6)
FN:79,(anonymous_7)
FNF:6
FNH:5
FNDA:7,connect
......@@ -26,38 +26,38 @@ FNDA:4,(anonymous_4)
FNDA:0,(anonymous_5)
FNDA:4,(anonymous_6)
FNDA:4,(anonymous_7)
DA:1,1
DA:2,1
DA:3,1
DA:4,1
DA:5,1
DA:7,1
DA:18,1
DA:37,1
DA:62,1
DA:6,1
DA:17,1
DA:36,1
DA:61,1
DA:62,7
DA:63,7
DA:64,7
DA:65,7
DA:68,7
DA:69,7
DA:70,7
DA:71,7
DA:72,7
DA:73,7
DA:73,4
DA:74,4
DA:75,4
DA:78,4
DA:80,7
DA:82,4
DA:77,4
DA:79,7
DA:81,4
DA:82,3
DA:83,3
DA:84,3
LF:23
LH:23
BRDA:62,0,0,1
BRDA:78,1,0,3
BRDA:78,1,1,1
BRDA:82,2,0,1
BRDA:82,2,1,3
BRDA:84,3,0,2
BRDA:84,3,1,1
BRDA:61,0,0,1
BRDA:77,1,0,3
BRDA:77,1,1,1
BRDA:81,2,0,1
BRDA:81,2,1,3
BRDA:83,3,0,2
BRDA:83,3,1,1
BRF:7
BRH:7
end_of_record
......
dist/lib/Driver.d.ts
View file @ 07824b9f
......@@ -4,7 +4,7 @@ import { IAsteroid } from '../config/asteroidInterfaces';
/**
* Connection options type
* @param host Rocket.Chat instance Host URL:PORT (without protocol)
* @param timeout How long to wait (ms) before abandonning connection
* @param timeout How long to wait (ms) before abandoning connection
*/
export interface IOptions {
host?: string;
......
dist/lib/Driver.js
View file @ 07824b9f
......@@ -10,7 +10,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
return result;
}
Object.defineProperty(exports, "__esModule", { value: true });
// @ts-ignore // Asteroid is not typed
const asteroid_1 = require("asteroid");
const events_1 = require("events");
const ws_1 = __importDefault(require("ws"));
......
dist/lib/Driver.js.map
View file @ 07824b9f
{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,sCAAsC;AACtC,uCAAsC;AACtC,mCAAqC;AACrC,4CAA0B;AAC1B,2DAA4C;AAE5C,MAAM,QAAQ,GAAG,sBAAW,EAAE,CAAA;AAWjB,QAAA,QAAQ,GAAa;IAChC,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa;CACjC,CAAA;AASD;;;;;;GAMG;AACU,QAAA,MAAM,GAAG,IAAI,qBAAY,EAAE,CAAA;AAOxC;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAyB,UAAoB,EAAE,EAAE,QAAoB;IACnE,MAAM,CAAC,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChD,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAQ,EAAE,OAAO,CAAC,CAAA;QAC1C,gBAAQ,GAAG,IAAI,QAAQ,CAAC;YACtB,QAAQ,EAAE,QAAQ,OAAO,CAAC,IAAI,YAAY;YAC1C,iBAAiB,EAAE,YAAS;SAC7B,CAAC,CAAA;QACF,WAAW,CAAC,GAAG,CAAC,gBAAQ,CAAC,CAAA,CAAC,+CAA+C;QACzE,gBAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,cAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAA;QACxD,gBAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,cAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAA;QAC5D,IAAI,SAAS,GAAG,KAAK,CAAA;QACrB,MAAM,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE;YACvC,SAAS,GAAG,IAAI,CAAA;YAChB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;YACpD,+CAA+C;YAC/C,oDAAoD;YACpD,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,gBAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACzD,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;QACnB,gBAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC9B,0DAA0D;YAC1D,EAAE,CAAC,CAAC,SAAS,CAAC;gBAAC,MAAM,CAAC,gBAAQ,CAAC,UAAU,EAAE,CAAA;YAC3C,YAAY,CAAC,gBAAgB,CAAC,CAAA;YAC9B,MAAM,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAQ,CAAC,CAAA;QAChF,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAzBD,0BAyBC","sourcesContent":["// @ts-ignore // Asteroid is not typed\nimport { createClass } from 'asteroid'\nimport { EventEmitter } from 'events'\nimport WebSocket from 'ws'\nimport * as methodCache from './methodCache'\nimport { IAsteroid } from '../config/asteroidInterfaces'\nconst Asteroid = createClass()\n\n/**\n * Connection options type\n * @param host Rocket.Chat instance Host URL:PORT (without protocol)\n * @param timeout How long to wait (ms) before abandonning connection\n */\nexport interface IOptions {\n host?: string,\n timeout?: number\n}\nexport const defaults: IOptions = {\n host: 'localhost:3000',\n timeout: 20 * 1000 // 20 seconds\n}\n\n/**\n * Error-first callback param type\n */\nexport interface ICallback {\n (error: Error | null, result?: any): void\n}\n\n/**\n * Event Emitter for listening to connection\n * @example\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect()\n * driver.events.on('connected', () => console.log('driver connected'))\n */\nexport const events = new EventEmitter()\n\n/**\n * An Asteroid instance for interacting with Rocket.Chat\n */\nexport let asteroid: IAsteroid\n\n/**\n * Initialise asteroid instance with given options or defaults\n * @example <caption>Use with callback</caption>\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect({}, (err, asteroid) => {\n * if (err) throw err\n * else constole.log(asteroid)\n * })\n * @example <caption>Using promise</caption>\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect()\n * .then((asteroid) => {\n * console.log(asteroid)\n * })\n * .catch((err) => {\n * console.error(err)\n * })\n */\nexport function connect (options: IOptions = {}, callback?: ICallback): Promise<any> {\n return new Promise<IAsteroid>((resolve, reject) => {\n options = Object.assign(defaults, options)\n asteroid = new Asteroid({\n endpoint: `ws://${options.host}/websocket`,\n SocketConstructor: WebSocket\n })\n methodCache.use(asteroid) // init instance for later caching method calls\n asteroid.on('connected', () => events.emit('connected'))\n asteroid.on('reconnected', () => events.emit('reconnected'))\n let cancelled = false\n const rejectionTimeout = setTimeout(() => {\n cancelled = true\n const err = new Error('Asteroid connection timeout')\n // if no callback available, reject the promise\n // else, return callback using \"error-first-pattern\"\n return callback ? callback(err, asteroid) : reject(err)\n }, options.timeout)\n asteroid.once('connected', () => {\n // cancel connection and don't resolve if already rejected\n if (cancelled) return asteroid.disconnect()\n clearTimeout(rejectionTimeout)\n return (callback !== undefined) ? callback(null, asteroid) : resolve(asteroid)\n })\n })\n}\n"]}
\ No newline at end of file
{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,uCAAsC;AACtC,mCAAqC;AACrC,4CAA0B;AAC1B,2DAA4C;AAE5C,MAAM,QAAQ,GAAG,sBAAW,EAAE,CAAA;AAWjB,QAAA,QAAQ,GAAa;IAChC,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa;CACjC,CAAA;AASD;;;;;;GAMG;AACU,QAAA,MAAM,GAAG,IAAI,qBAAY,EAAE,CAAA;AAOxC;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAyB,UAAoB,EAAE,EAAE,QAAoB;IACnE,MAAM,CAAC,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChD,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAQ,EAAE,OAAO,CAAC,CAAA;QAC1C,gBAAQ,GAAG,IAAI,QAAQ,CAAC;YACtB,QAAQ,EAAE,QAAQ,OAAO,CAAC,IAAI,YAAY;YAC1C,iBAAiB,EAAE,YAAS;SAC7B,CAAC,CAAA;QACF,WAAW,CAAC,GAAG,CAAC,gBAAQ,CAAC,CAAA,CAAC,+CAA+C;QACzE,gBAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,cAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAA;QACxD,gBAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,cAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAA;QAC5D,IAAI,SAAS,GAAG,KAAK,CAAA;QACrB,MAAM,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE;YACvC,SAAS,GAAG,IAAI,CAAA;YAChB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;YACpD,+CAA+C;YAC/C,oDAAoD;YACpD,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,gBAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACzD,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;QACnB,gBAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC9B,0DAA0D;YAC1D,EAAE,CAAC,CAAC,SAAS,CAAC;gBAAC,MAAM,CAAC,gBAAQ,CAAC,UAAU,EAAE,CAAA;YAC3C,YAAY,CAAC,gBAAgB,CAAC,CAAA;YAC9B,MAAM,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAQ,CAAC,CAAA;QAChF,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAzBD,0BAyBC","sourcesContent":["import { createClass } from 'asteroid'\nimport { EventEmitter } from 'events'\nimport WebSocket from 'ws'\nimport * as methodCache from './methodCache'\nimport { IAsteroid } from '../config/asteroidInterfaces'\nconst Asteroid = createClass()\n\n/**\n * Connection options type\n * @param host Rocket.Chat instance Host URL:PORT (without protocol)\n * @param timeout How long to wait (ms) before abandoning connection\n */\nexport interface IOptions {\n host?: string,\n timeout?: number\n}\nexport const defaults: IOptions = {\n host: 'localhost:3000',\n timeout: 20 * 1000 // 20 seconds\n}\n\n/**\n * Error-first callback param type\n */\nexport interface ICallback {\n (error: Error | null, result?: any): void\n}\n\n/**\n * Event Emitter for listening to connection\n * @example\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect()\n * driver.events.on('connected', () => console.log('driver connected'))\n */\nexport const events = new EventEmitter()\n\n/**\n * An Asteroid instance for interacting with Rocket.Chat\n */\nexport let asteroid: IAsteroid\n\n/**\n * Initialise asteroid instance with given options or defaults\n * @example <caption>Use with callback</caption>\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect({}, (err, asteroid) => {\n * if (err) throw err\n * else constole.log(asteroid)\n * })\n * @example <caption>Using promise</caption>\n * import { driver } from 'rocketchat-bot-driver'\n * driver.connect()\n * .then((asteroid) => {\n * console.log(asteroid)\n * })\n * .catch((err) => {\n * console.error(err)\n * })\n */\nexport function connect (options: IOptions = {}, callback?: ICallback): Promise<any> {\n return new Promise<IAsteroid>((resolve, reject) => {\n options = Object.assign(defaults, options)\n asteroid = new Asteroid({\n endpoint: `ws://${options.host}/websocket`,\n SocketConstructor: WebSocket\n })\n methodCache.use(asteroid) // init instance for later caching method calls\n asteroid.on('connected', () => events.emit('connected'))\n asteroid.on('reconnected', () => events.emit('reconnected'))\n let cancelled = false\n const rejectionTimeout = setTimeout(() => {\n cancelled = true\n const err = new Error('Asteroid connection timeout')\n // if no callback available, reject the promise\n // else, return callback using \"error-first-pattern\"\n return callback ? callback(err, asteroid) : reject(err)\n }, options.timeout)\n asteroid.once('connected', () => {\n // cancel connection and don't resolve if already rejected\n if (cancelled) return asteroid.disconnect()\n clearTimeout(rejectionTimeout)\n return (callback !== undefined) ? callback(null, asteroid) : resolve(asteroid)\n })\n })\n}\n"]}
\ No newline at end of file
docs/globals.html
View file @ 07824b9f
......@@ -912,9 +912,108 @@ img { max-width: 100%; }
<div class="container container-main">
<div class="content-wrap">
<div class="tsd-panel tsd-typography">
<h1 id="rocketchat-bot-driver">rocketchat-bot-driver</h1>
<p>Agnostic interface for bot adaptors to interact with Rocket.Chat</p>
<h3 id="work-in-progress">WORK IN PROGRESS</h3>
<h1 id="rocket-chat-bot-driver">Rocket.Chat Bot Driver</h1>
<p>An agnostic interface for bot adaptors to interact with Rocket.Chat</p>
<h2 id="overview">Overview</h2>
<p>Rocket.Chat makes it easy for bot makers to provide the best solutions and
experience for their community. The internal Hubot and adapter enables chat-ops
workflows and multi-channel, multi-user, public and private interactions.</p>
<p>This package provides the core interface to subscribe to message streams, send
messages and query user details.</p>
<p>We have more bot features and adapters on the roadmap and encourage the
community to implement this driver to provide adapters for their bot framework
or platform of choice.</p>
<h2 id="api">API</h2>
<p>See full API documentation links in the generated docs. Below is just a summary:</p>
<hr>
<h3 id="driver-connect-options-cb-"><code>driver.connect(options, cb?)</code></h3>
<ul>
<li>Options accepts <code>host</code> and <code>timeout</code></li>
<li>Returns an <a href="https://www.npmjs.com/package/asteroid">asteroid</a> instance</li>
<li>Can return a promise, or use error-first callback pattern</li>
</ul>
<h2 id="see-asteroid-docs-for-methods-that-can-be-called-from-that-api-">See <a href="https://www.npmjs.com/package/asteroid">Asteroid</a> docs for methods that can be called from that API.</h2>
<h2 id="getting-started">Getting Started</h2>
<p>A local instance of Rocket.Chat is required for unit tests to confirm connection
and subscription methods are functional. And it helps to manually run your bot
interactions locally while in development.</p>
<h2 id="use-as-dependency">Use as Dependency</h2>
<p><code>yarn add rocketchat-bot-driver</code> or <code>npm install --save rocketchat-bot-driver</code></p>
<p>ES6 Module, using async</p>
<pre><code><span class="hljs-keyword">import</span> { driver } <span class="hljs-keyword">from</span> <span class="hljs-string">'rocketchat-bot-driver'</span>
<span class="hljs-keyword">const</span> asteroid = <span class="hljs-keyword">await</span> driver.connect({ <span class="hljs-attr">host</span>: <span class="hljs-string">'localhost:3000'</span> })
</code></pre><p>More to come...</p>
<h2 id="develop-test">Develop &amp; Test</h2>
<h3 id="settings">Settings</h3>
<table>
<thead>
<tr>
<th>Env var</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ROCKETCHAT_URL</code></td>
<td>URL of the Rocket.Chat to connect to</td>
</tr>
<tr>
<td><code>ADMIN_USERNAME</code></td>
<td>Admin user password for API</td>
</tr>
<tr>
<td><code>ADMIN_PASS</code></td>
<td>Admin user password for API</td>
</tr>
<tr>
<td><code>ROCKETCHAT_USER</code></td>
<td>Bot password for tests</td>
</tr>
<tr>
<td><code>ROCKETCHAT_PASS</code></td>
<td>Bot username for tests</td>
</tr>
</tbody>
</table>
<p>These are only required in test and development, assuming in production they
will be passed from the adapter implementing this package.</p>
<p>If a <code>.env</code> file exists in the project folder, it will be used by <code>dotenv</code>.</p>
<h3 id="installing-rocket-chat">Installing Rocket.Chat</h3>
<p>Clone and run a new instance of Rocket.Chat locally, using either the internal
mongo or a dedicated local mongo for testing, so the bot can&#39;t affect any other
Rocket.Chat development you might do locally.</p>
<p>The following will provision a default admin user on build, so it can be used to
access the API, allowing bot driver utils to prepare for and clean up tests.</p>
<ul>
<li><code>git clone https://github.com/RocketChat/Rocket.Chat.git rc-bot-test</code></li>
<li><code>cd rc-bot-test</code></li>
<li><code>meteor npm install</code></li>
<li><code>export ADMIN_PASS=pass; export ADMIN_USERNAME=admin; export MONGO_URL=&#39;mongodb://localhost:27017/rc-bot-test&#39;; meteor</code></li>
</ul>
<p>Using <code>yarn</code> to run local tests and build scripts is recommended.</p>
<p>Do <code>npm install -g yarn</code> if you don&#39;t have it. Then setup the project:</p>
<ul>
<li><code>git clone https://github.com/RocketChat/rocketchat-bot-driver</code></li>
<li><code>cd rocketchat-bot-driver</code></li>
<li><code>yarn</code></li>
</ul>
<h3 id="test-scripts">Test Scripts</h3>
<ul>
<li><code>yarn test</code> runs tests and coverage locally</li>
<li><code>yarn test:debug</code> runs tests without coverage, breaking for debug attach</li>
<li><code>yarn docs</code> generates docs</li>
<li><code>yarn build</code> runs tests, coverage, compiles and generates docs</li>
</ul>
<p><code>yarn:hook</code> is run on git push hooks to prevent publishing with failing tests.</p>
<h3 id="integration-tests">Integration Tests</h3>
<p>The node scripts in <code>utils</code> are used to prepare for and clean up after test
interactions. They use the Rocket.Chat API to create a bot user and a mock human
user (benny) for the bot to interact with. They <em>should</em> restore the pre-test
state but it is always advised to only run tests with a connection to a clean
local instance of Rocket.Chat.</p>
<h3 id="debugging">Debugging</h3>
<p>Configs are included in source for VS Code using Wallaby or Mocha Sidebar.</p>
</div>
<section class="tsd-panel-group tsd-index-group">
<h2>Index</h2>
......
docs/index.html
View file @ 07824b9f
......@@ -912,9 +912,108 @@ img { max-width: 100%; }
<div class="container container-main">
<div class="content-wrap">
<div class="tsd-panel tsd-typography">
<h1 id="rocketchat-bot-driver">rocketchat-bot-driver</h1>
<p>Agnostic interface for bot adaptors to interact with Rocket.Chat</p>
<h3 id="work-in-progress">WORK IN PROGRESS</h3>
<h1 id="rocket-chat-bot-driver">Rocket.Chat Bot Driver</h1>
<p>An agnostic interface for bot adaptors to interact with Rocket.Chat</p>
<h2 id="overview">Overview</h2>
<p>Rocket.Chat makes it easy for bot makers to provide the best solutions and
experience for their community. The internal Hubot and adapter enables chat-ops
workflows and multi-channel, multi-user, public and private interactions.</p>
<p>This package provides the core interface to subscribe to message streams, send
messages and query user details.</p>
<p>We have more bot features and adapters on the roadmap and encourage the
community to implement this driver to provide adapters for their bot framework
or platform of choice.</p>
<h2 id="api">API</h2>
<p>See full API documentation links in the generated docs. Below is just a summary:</p>
<hr>
<h3 id="driver-connect-options-cb-"><code>driver.connect(options, cb?)</code></h3>
<ul>
<li>Options accepts <code>host</code> and <code>timeout</code></li>
<li>Returns an <a href="https://www.npmjs.com/package/asteroid">asteroid</a> instance</li>
<li>Can return a promise, or use error-first callback pattern</li>
</ul>
<h2 id="see-asteroid-docs-for-methods-that-can-be-called-from-that-api-">See <a href="https://www.npmjs.com/package/asteroid">Asteroid</a> docs for methods that can be called from that API.</h2>
<h2 id="getting-started">Getting Started</h2>
<p>A local instance of Rocket.Chat is required for unit tests to confirm connection
and subscription methods are functional. And it helps to manually run your bot
interactions locally while in development.</p>
<h2 id="use-as-dependency">Use as Dependency</h2>
<p><code>yarn add rocketchat-bot-driver</code> or <code>npm install --save rocketchat-bot-driver</code></p>
<p>ES6 Module, using async</p>
<pre><code><span class="hljs-keyword">import</span> { driver } <span class="hljs-keyword">from</span> <span class="hljs-string">'rocketchat-bot-driver'</span>
<span class="hljs-keyword">const</span> asteroid = <span class="hljs-keyword">await</span> driver.connect({ <span class="hljs-attr">host</span>: <span class="hljs-string">'localhost:3000'</span> })
</code></pre><p>More to come...</p>
<h2 id="develop-test">Develop &amp; Test</h2>
<h3 id="settings">Settings</h3>
<table>
<thead>
<tr>
<th>Env var</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ROCKETCHAT_URL</code></td>
<td>URL of the Rocket.Chat to connect to</td>
</tr>
<tr>
<td><code>ADMIN_USERNAME</code></td>
<td>Admin user password for API</td>
</tr>
<tr>
<td><code>ADMIN_PASS</code></td>
<td>Admin user password for API</td>
</tr>
<tr>
<td><code>ROCKETCHAT_USER</code></td>
<td>Bot password for tests</td>
</tr>
<tr>
<td><code>ROCKETCHAT_PASS</code></td>
<td>Bot username for tests</td>
</tr>
</tbody>
</table>
<p>These are only required in test and development, assuming in production they
will be passed from the adapter implementing this package.</p>
<p>If a <code>.env</code> file exists in the project folder, it will be used by <code>dotenv</code>.</p>
<h3 id="installing-rocket-chat">Installing Rocket.Chat</h3>
<p>Clone and run a new instance of Rocket.Chat locally, using either the internal
mongo or a dedicated local mongo for testing, so the bot can&#39;t affect any other
Rocket.Chat development you might do locally.</p>
<p>The following will provision a default admin user on build, so it can be used to
access the API, allowing bot driver utils to prepare for and clean up tests.</p>
<ul>
<li><code>git clone https://github.com/RocketChat/Rocket.Chat.git rc-bot-test</code></li>
<li><code>cd rc-bot-test</code></li>
<li><code>meteor npm install</code></li>
<li><code>export ADMIN_PASS=pass; export ADMIN_USERNAME=admin; export MONGO_URL=&#39;mongodb://localhost:27017/rc-bot-test&#39;; meteor</code></li>
</ul>
<p>Using <code>yarn</code> to run local tests and build scripts is recommended.</p>
<p>Do <code>npm install -g yarn</code> if you don&#39;t have it. Then setup the project:</p>
<ul>
<li><code>git clone https://github.com/RocketChat/rocketchat-bot-driver</code></li>
<li><code>cd rocketchat-bot-driver</code></li>
<li><code>yarn</code></li>
</ul>
<h3 id="test-scripts">Test Scripts</h3>
<ul>
<li><code>yarn test</code> runs tests and coverage locally</li>
<li><code>yarn test:debug</code> runs tests without coverage, breaking for debug attach</li>
<li><code>yarn docs</code> generates docs</li>
<li><code>yarn build</code> runs tests, coverage, compiles and generates docs</li>
</ul>
<p><code>yarn:hook</code> is run on git push hooks to prevent publishing with failing tests.</p>
<h3 id="integration-tests">Integration Tests</h3>
<p>The node scripts in <code>utils</code> are used to prepare for and clean up after test
interactions. They use the Rocket.Chat API to create a bot user and a mock human
user (benny) for the bot to interact with. They <em>should</em> restore the pre-test
state but it is always advised to only run tests with a connection to a clean
local instance of Rocket.Chat.</p>
<h3 id="debugging">Debugging</h3>
<p>Configs are included in source for VS Code using Wallaby or Mocha Sidebar.</p>
</div>
<div style="position:relative;"><a name="typedoc-main-index" class="tsd-anchor"></a></div>
<section class="tsd-panel-group tsd-index-group">
......
docs/interfaces/_config_asteroidinterfaces_.iasteroid.html
View file @ 07824b9f
......@@ -1084,7 +1084,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">apply<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:12</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L12">config/asteroidInterfaces.ts:12</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1118,7 +1118,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">call<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:11</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L11">config/asteroidInterfaces.ts:11</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1152,7 +1152,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">connect<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:9</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L9">config/asteroidInterfaces.ts:9</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1177,7 +1177,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">create<wbr>User<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:16</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L16">config/asteroidInterfaces.ts:16</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1208,7 +1208,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">ddp<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">object</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:8</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L8">config/asteroidInterfaces.ts:8</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1265,7 +1265,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">disconnect<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:10</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L10">config/asteroidInterfaces.ts:10</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1290,7 +1290,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">login<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:18</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L18">config/asteroidInterfaces.ts:18</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1321,7 +1321,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">login<wbr>With<wbr>Password<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:17</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L17">config/asteroidInterfaces.ts:17</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1352,7 +1352,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">logout<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:19</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L19">config/asteroidInterfaces.ts:19</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1377,7 +1377,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">subscribe<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:13</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L13">config/asteroidInterfaces.ts:13</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......@@ -1411,7 +1411,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">subscriptions<span class="tsd-signature-symbol">:</span> <a href="_config_asteroidinterfaces_.isubscription.html" class="tsd-signature-type">ISubscription</a><span class="tsd-signature-symbol">[]</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:14</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L14">config/asteroidInterfaces.ts:14</a></li>
</ul>
</aside>
</section>
......@@ -1421,7 +1421,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">unsubscribe<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">function</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:15</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L15">config/asteroidInterfaces.ts:15</a></li>
</ul>
</aside>
<div class="tsd-type-declaration">
......
docs/interfaces/_config_asteroidinterfaces_.isubscription.html
View file @ 07824b9f
......@@ -1040,7 +1040,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">id<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:27</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L27">config/asteroidInterfaces.ts:27</a></li>
</ul>
</aside>
</section>
......
docs/interfaces/_config_asteroidinterfaces_.iuseroptions.html
View file @ 07824b9f
......@@ -974,7 +974,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">email<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">undefined</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type">string</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:36</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L36">config/asteroidInterfaces.ts:36</a></li>
</ul>
</aside>
</section>
......@@ -984,7 +984,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">password<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:37</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L37">config/asteroidInterfaces.ts:37</a></li>
</ul>
</aside>
</section>
......@@ -994,7 +994,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">username<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">undefined</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type">string</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in config/asteroidInterfaces.ts:35</li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/config/asteroidInterfaces.ts#L35">config/asteroidInterfaces.ts:35</a></li>
</ul>
</aside>
</section>
......
docs/interfaces/_lib_driver_.icallback.html
View file @ 07824b9f
......@@ -956,7 +956,7 @@ img { max-width: 100%; }
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/71f6e27/src/lib/driver.ts#L26">lib/driver.ts:26</a></li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/lib/driver.ts#L25">lib/driver.ts:25</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
......
docs/interfaces/_lib_driver_.ioptions.html
View file @ 07824b9f
......@@ -950,7 +950,7 @@ img { max-width: 100%; }
<dd><p>Rocket.Chat instance Host URL:PORT (without protocol)</p>
</dd>
<dt>param</dt>
<dd><p>How long to wait (ms) before abandonning connection</p>
<dd><p>How long to wait (ms) before abandoning connection</p>
</dd>
</dl>
</div>
......@@ -985,7 +985,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">host<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">undefined</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type">string</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/71f6e27/src/lib/driver.ts#L15">lib/driver.ts:15</a></li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/lib/driver.ts#L14">lib/driver.ts:14</a></li>
</ul>
</aside>
</section>
......@@ -995,7 +995,7 @@ img { max-width: 100%; }
<div class="tsd-signature tsd-kind-icon">timeout<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">undefined</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type">number</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/71f6e27/src/lib/driver.ts#L16">lib/driver.ts:16</a></li>
<li>Defined in <a href="https://github.com/RocketChat/rocketchat-bot-driver/blob/32210a8/src/lib/driver.ts#L15">lib/driver.ts:15</a></li>
</ul>
</aside>
</section>
......