README.md 4.72 KB
Newer Older
1
[asteroid]: https://www.npmjs.com/package/asteroid
2

3
# Rocket.Chat Node.js SDK
4

5
Application interface for server methods and message stream subscriptions.
6 7 8

## Overview

9 10 11
Using this package third party apps can control and query a Rocket.Chat server
instance, via Asteroid login and method calls as well as DDP for subscribing
to stream events.
12

13 14 15
Designed especially for chat automation, this SDK makes it easy for bot and
integration developers to provide the best solutions and experience for their
community.
16

17 18
For example, the Hubot Rocketchat adapter uses this package to enable chat-ops
workflows and multi-channel, multi-user, public and private interactions.
19
We have more bot features and adapters on the roadmap and encourage the
20
community to implement this SDK to provide adapters for their bot framework
21 22 23 24 25 26 27
or platform of choice.

## API

See full API documentation links in the generated docs. Below is just a summary:

---
28

29
### `.connect(options, cb?)`
30

31
- Options accepts `host` and `timeout` attributes
32
- Can return a promise, or use error-first callback pattern
33
- Resolves with an [asteroid][asteroid] instance
34 35

See [Asteroid][asteroid] docs for methods that can be called from that API.
36

37 38 39 40 41
---

## Getting Started

A local instance of Rocket.Chat is required for unit tests to confirm connection
42 43
and subscription methods are functional. And it helps to manually run your SDK
interactions (i.e. bots) locally while in development.
44 45 46

## Use as Dependency

47 48 49 50 51 52
`yarn add @rocket.chat/sdk` or `npm install --save @rocket.chat/sdk`

ES6 module, using async

```
import * as rocketchat from '@rocket.chat/sdk'
53

54 55
const asteroid = await rocketchat.connect({ host: 'localhost:3000' })
console.log('connected', asteroid)
56 57
```

58 59
ES5 module, using callback

60
```
61
const rocketchat = require('@rocket.chat/sdk')
62

63 64 65 66 67
rocketchat.connect({ host: 'localhost:3000' }, function (err, asteroid) {
  if (err) console.error(err)
  else console.log('connected', asteroid)
})
```
68 69 70 71 72 73 74 75

## Develop & Test

### Settings

| Env var | Description |
| --------------------- | ---------------------------------------------------- |
| `ROCKETCHAT_URL` | URL of the Rocket.Chat to connect to |
76
| `ROCKETCHAT_AUTH` | Set to 'ldap' to enable LDAP login |
77 78
| `ADMIN_USERNAME` | Admin user password for API |
| `ADMIN_PASS` | Admin user password for API |
79 80
| `ROCKETCHAT_USER` | User password for SDK tests |
| `ROCKETCHAT_PASS` | Pass username for SDK tests |
81 82 83 84
| `ROOM_CACHE_SIZE` | Size of cache (LRU) for room (ID or name) lookups |
| `ROOM_CACHE_MAX_AGE` | Max age of cache for room lookups |
| `DM_ROOM_CACHE_SIZE` | Size of cache for Direct Message room lookups |
| `DM_ROOM_CACHE_MAX_AGE` | Max age of cache for DM lookups |
85 86 87 88 89 90 91

These are only required in test and development, assuming in production they
will be passed from the adapter implementing this package.

### Installing Rocket.Chat

Clone and run a new instance of Rocket.Chat locally, using either the internal
92
mongo or a dedicated local mongo for testing, so you won't affect any other
93 94 95
Rocket.Chat development you might do locally.

The following will provision a default admin user on build, so it can be used to
96
access the API, allowing SDK utils to prepare for and clean up tests.
97

98 99
- `git clone https://github.com/RocketChat/Rocket.Chat.git rc-sdk-test`
- `cd rc-sdk-test`
100
- `meteor npm install`
101
- `export ADMIN_PASS=pass; export ADMIN_USERNAME=admin; export MONGO_URL='mongodb://localhost:27017/rc-sdk-test'; meteor`
102 103 104 105 106

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:

107 108
- `git clone https://github.com/RocketChat/Rocket.Chat.js.SDK.git`
- `cd Rocket.Chat.js.SDK`
109 110
- `yarn`

111
### Test and Build Scripts
112

113
- `yarn test` runs tests and coverage locally (pretest does lint)
114 115
- `yarn test:debug` runs tests without coverage, breaking for debug attach
- `yarn docs` generates docs
116 117 118 119
- `yarn build` runs tests, coverage, compiles, tests package, generates docs
- `yarn test:package` uses package-preview to make sure the published node
package can be required and run only with defined dependencies, to avoid errors
that might pass locally due to existing global dependencies or symlinks.
120

121 122
`yarn:hook` is run on git push hooks to prevent publishing with failing tests,
but won't change coverage to avoid making any working copy changes after commit.
123 124 125 126 127 128 129

### 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
130
local or fresh re-usable container instance of Rocket.Chat.
131 132 133 134

### Debugging

Configs are included in source for VS Code using Wallaby or Mocha Sidebar.