Commit c8bf796d authored by timkinnane's avatar timkinnane

feat(respond): New method provides shortcut to config filtered stream

+ Also updated some interfaces and docs
parent 2c3f50e9
......@@ -43,8 +43,43 @@ Any Rocket.Chat server method can be called via `driver.callMethod`,
`driver.cacheCall` or `driver.asyncCall`. Server methods are not fully
documented, most require searching the Rocket.Chat codebase.
### BASIC USAGE
---
The following ES6 demo uses async calls to login, join rooms, subscribe to
message streams and respond to messages (with a callback) using provided
options to filter the types of messages to respond to.
This example can be executed with the testing instance by running `yarn start`,
to allow manual testing, once subscription is setup try sending DMs to the bot
user and they should be logged in console.
```
import { driver } from '@rocket.chat/sdk'
async function startReceiving () {
await driver.connect({ host: 'localhost:3000', useSsl: true })
await driver.login({ username: 'bot', password: 'pass' })
await driver.joinRooms(['GENERAL'])
await driver.subscribeToMessages()
await driver.respondToMessages((err, message, msgOpts) => {
console.log('received message', message, msgOpts)
}, {
allPublic: false,
dm: true,
livechat: false,
edited: true
})
}
startReceiving()
```
#### MESSAGE OBJECTS
---
The Rocket.Chat message schema can be found here:
https://rocket.chat/docs/developer-guides/schema-definition/
......@@ -114,7 +149,7 @@ Shortcut to subscribe to user's message stream
Once a subscription is created, using `driver.subscribeToMessages()` this method
can be used to attach a callback to changes in the message stream.
Fires callback with every change in subscriptions
Fires callback with every change in subscriptions.
- Uses error-first callback pattern
- Second argument is the changed item
- Third argument is additional attributes, such as `roomType`
......@@ -123,6 +158,22 @@ For example usage, see the Rocket.Chat Hubot adapter's receive function, which
is bound as a callback to this method:
https://github.com/RocketChat/hubot-rocketchat/blob/convert-es6/index.js#L97-L193
### `driver.respondToMessages(callback, options)`
Proxy for `reactToMessages` with some filtering of messages based on config.
This is a more user-friendly method for bots to subscribe to a message stream.
Fires callback after filters run on subscription events.
- Uses error-first callback pattern
- Second argument is the changed item
- Third argument is additional attributes, such as `roomType`
Accepts options object, that parallels respond filter env variables:
- options.allPublic : respond to messages on all channels (or just joined)
- options.dm : respond to messages in DMs with the SDK user
- options.livechat : respond to messages in Livechat rooms
- options.edited : respond to edited messages
### `driver.asyncCall(method, params)`
Wraps server method calls to always be async
......@@ -298,19 +349,23 @@ rocketchat.driver.connect({ host: 'localhost:3000' }, function (err, asteroid) {
### Settings
| Env var | Description |
| --------------------- | ---------------------------------------------------- |
| `ROCKETCHAT_URL` | URL of the Rocket.Chat to connect to |
| `ROCKETCHAT_AUTH` | Set to 'ldap' to enable LDAP login |
| `ADMIN_USERNAME` | Admin user password for API |
| `ADMIN_PASS` | Admin user password for API |
| `ROCKETCHAT_USER` | User password for SDK tests |
| `ROCKETCHAT_PASS` | Pass username for SDK tests |
| `INTEGRATION_ID` | ID applied to message object to integration source |
| `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 |
| Env var | Description |
| ---------------------- | ----------------------------------------------------- |
| `ROCKETCHAT_URL` | URL of the Rocket.Chat to connect to |
| `ROCKETCHAT_AUTH` | Set to 'ldap' to enable LDAP login |
| `ADMIN_USERNAME` | Admin user password for API |
| `ADMIN_PASS` | Admin user password for API |
| `ROCKETCHAT_USER` | User password for SDK tests |
| `ROCKETCHAT_PASS` | Pass username for SDK tests |
| `INTEGRATION_ID` | ID applied to message object to integration source |
| `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 |
| `LISTEN_ON_ALL_PUBLIC` | true/false, respond listens in all public channels |
| `RESPOND_TO_LIVECHAT` | true/false, respond listens in livechat |
| `RESPOND_TO_DM` | true/false, respond listens to DMs with bot |
| `RESPOND_TO_EDITED` | true/false, respond listens to edited messages |
These are only required in test and development, assuming in production they
will be passed from the adapter implementing this package.
......
TN:
SF:/Volumes/x/code/Rocket.Chat.js.SDK/src/lib/driver.ts
FN:78,useLog
FN:99,connect
FN:100,(anonymous_4)
FN:113,(anonymous_5)
FN:114,(anonymous_6)
FN:116,(anonymous_7)
FN:122,(anonymous_8)
FN:135,disconnect
FN:138,(anonymous_10)
FN:148,setupMethodCache
FN:169,asyncCall
FN:173,(anonymous_13)
FN:177,(anonymous_14)
FN:190,callMethod
FN:201,cacheCall
FN:203,(anonymous_17)
FN:207,(anonymous_18)
FN:219,login
FN:233,(anonymous_20)
FN:240,logout
FN:241,(anonymous_22)
FN:252,subscribe
FN:253,(anonymous_24)
FN:257,(anonymous_25)
FN:279,unsubscribe
FN:289,unsubscribeAll
FN:290,(anonymous_28)
FN:297,subscribeToMessages
FN:299,(anonymous_30)
FN:307,reactToMessages
FN:309,(anonymous_32)
FN:350,getRoomId
FN:355,getRoomName
FN:364,getDirectMessageRoomId
FN:365,(anonymous_36)
FN:369,joinRoom
FN:370,(anonymous_38)
FN:374,joinRooms
FN:375,(anonymous_40)
FN:382,prepareMessage
FN:393,sendMessageByRoomId
FN:396,(anonymous_43)
FN:400,(anonymous_44)
FN:408,sendMessageByRoom
FN:409,(anonymous_46)
FN:415,sendDirectToUser
FN:416,(anonymous_48)
FN:425,sendMessage
FN:434,customMessage
FNF:49
FNH:19
FN:36,connectDefaults
FN:45,respondDefaults
FN:98,useLog
FN:119,connect
FN:120,(anonymous_6)
FN:133,(anonymous_7)
FN:134,(anonymous_8)
FN:136,(anonymous_9)
FN:142,(anonymous_10)
FN:155,disconnect
FN:158,(anonymous_12)
FN:168,setupMethodCache
FN:189,asyncCall
FN:193,(anonymous_15)
FN:197,(anonymous_16)
FN:210,callMethod
FN:221,cacheCall
FN:223,(anonymous_19)
FN:227,(anonymous_20)
FN:239,login
FN:254,(anonymous_22)
FN:258,(anonymous_23)
FN:265,logout
FN:266,(anonymous_25)
FN:277,subscribe
FN:278,(anonymous_27)
FN:282,(anonymous_28)
FN:304,unsubscribe
FN:314,unsubscribeAll
FN:315,(anonymous_31)
FN:322,subscribeToMessages
FN:324,(anonymous_33)
FN:344,reactToMessages
FN:346,(anonymous_35)
FN:362,respondToMessages
FN:365,(anonymous_37)
FN:433,getRoomId
FN:438,getRoomName
FN:447,getDirectMessageRoomId
FN:448,(anonymous_41)
FN:452,joinRoom
FN:453,(anonymous_43)
FN:457,joinRooms
FN:458,(anonymous_45)
FN:465,prepareMessage
FN:476,sendMessageByRoomId
FN:479,(anonymous_48)
FN:483,(anonymous_49)
FN:491,sendMessageByRoom
FN:492,(anonymous_51)
FN:498,sendDirectToUser
FN:499,(anonymous_53)
FN:508,sendMessage
FN:517,customMessage
FNF:54
FNH:24
FNDA:11,connectDefaults
FNDA:8,respondDefaults
FNDA:0,useLog
FNDA:5,connect
FNDA:5,(anonymous_4)
FNDA:5,(anonymous_5)
FNDA:0,(anonymous_6)
FNDA:0,(anonymous_7)
FNDA:5,(anonymous_8)
FNDA:11,connect
FNDA:11,(anonymous_6)
FNDA:11,(anonymous_7)
FNDA:0,(anonymous_8)
FNDA:0,(anonymous_9)
FNDA:11,(anonymous_10)
FNDA:0,disconnect
FNDA:0,(anonymous_10)
FNDA:5,setupMethodCache
FNDA:1,asyncCall
FNDA:0,(anonymous_13)
FNDA:1,(anonymous_14)
FNDA:0,(anonymous_12)
FNDA:11,setupMethodCache
FNDA:2,asyncCall
FNDA:0,(anonymous_15)
FNDA:2,(anonymous_16)
FNDA:0,callMethod
FNDA:0,cacheCall
FNDA:0,(anonymous_17)
FNDA:0,(anonymous_18)
FNDA:5,login
FNDA:0,(anonymous_19)
FNDA:0,(anonymous_20)
FNDA:11,login
FNDA:11,(anonymous_22)
FNDA:0,(anonymous_23)
FNDA:0,logout
FNDA:0,(anonymous_22)
FNDA:4,subscribe
FNDA:4,(anonymous_24)
FNDA:4,(anonymous_25)
FNDA:0,(anonymous_25)
FNDA:10,subscribe
FNDA:10,(anonymous_27)
FNDA:10,(anonymous_28)
FNDA:0,unsubscribe
FNDA:0,unsubscribeAll
FNDA:0,(anonymous_28)
FNDA:4,subscribeToMessages
FNDA:4,(anonymous_30)
FNDA:2,reactToMessages
FNDA:6,(anonymous_32)
FNDA:0,(anonymous_31)
FNDA:10,subscribeToMessages
FNDA:10,(anonymous_33)
FNDA:8,reactToMessages
FNDA:48,(anonymous_35)
FNDA:6,respondToMessages
FNDA:11,(anonymous_37)
FNDA:0,getRoomId
FNDA:0,getRoomName
FNDA:0,getDirectMessageRoomId
FNDA:0,(anonymous_36)
FNDA:0,(anonymous_41)
FNDA:0,joinRoom
FNDA:0,(anonymous_38)
FNDA:0,joinRooms
FNDA:0,(anonymous_40)
FNDA:1,prepareMessage
FNDA:1,sendMessageByRoomId
FNDA:0,(anonymous_43)
FNDA:1,(anonymous_44)
FNDA:0,joinRooms
FNDA:0,(anonymous_45)
FNDA:2,prepareMessage
FNDA:2,sendMessageByRoomId
FNDA:0,(anonymous_48)
FNDA:2,(anonymous_49)
FNDA:0,sendMessageByRoom
FNDA:0,(anonymous_46)
FNDA:0,(anonymous_51)
FNDA:0,sendDirectToUser
FNDA:0,(anonymous_48)
FNDA:1,sendMessage
FNDA:0,(anonymous_53)
FNDA:2,sendMessage
FNDA:0,customMessage
DA:1,1
DA:2,1
......@@ -108,182 +118,245 @@ DA:15,1
DA:18,1
DA:19,1
DA:36,1
DA:47,1
DA:56,1
DA:68,1
DA:78,1
DA:79,0
DA:99,1
DA:100,5
DA:101,5
DA:102,5
DA:103,5
DA:104,5
DA:112,5
DA:113,5
DA:114,5
DA:116,5
DA:117,0
DA:119,0
DA:120,0
DA:122,5
DA:123,5
DA:125,5
DA:126,5
DA:127,5
DA:135,1
DA:136,0
DA:37,11
DA:45,1
DA:46,8
DA:62,1
DA:71,1
DA:83,1
DA:98,1
DA:99,0
DA:119,1
DA:120,11
DA:121,11
DA:122,11
DA:123,11
DA:124,11
DA:132,11
DA:133,11
DA:134,11
DA:136,11
DA:137,0
DA:138,0
DA:149,5
DA:150,5
DA:158,5
DA:169,1
DA:170,1
DA:171,1
DA:172,1
DA:174,0
DA:175,0
DA:178,1
DA:181,1
DA:190,1
DA:191,0
DA:201,1
DA:202,0
DA:204,0
DA:205,0
DA:208,0
DA:139,0
DA:140,0
DA:142,11
DA:143,11
DA:145,11
DA:146,11
DA:147,11
DA:155,1
DA:156,0
DA:157,0
DA:158,0
DA:169,11
DA:170,11
DA:178,11
DA:189,1
DA:190,2
DA:191,2
DA:192,2
DA:194,0
DA:195,0
DA:198,2
DA:201,2
DA:210,1
DA:211,0
DA:219,1
DA:220,5
DA:222,5
DA:223,0
DA:221,1
DA:222,0
DA:224,0
DA:225,0
DA:228,0
DA:230,5
DA:231,5
DA:233,5
DA:234,0
DA:235,0
DA:240,1
DA:241,0
DA:242,0
DA:231,0
DA:239,1
DA:240,11
DA:242,11
DA:243,0
DA:252,1
DA:253,4
DA:254,4
DA:255,4
DA:256,4
DA:257,4
DA:258,4
DA:259,4
DA:279,1
DA:280,0
DA:281,0
DA:282,0
DA:284,0
DA:285,0
DA:289,1
DA:290,0
DA:297,1
DA:298,4
DA:300,4
DA:303,4
DA:307,1
DA:308,2
DA:309,2
DA:310,6
DA:311,6
DA:312,6
DA:313,6
DA:314,3
DA:315,3
DA:317,3
DA:320,0
DA:350,1
DA:351,0
DA:355,1
DA:356,0
DA:364,1
DA:365,0
DA:369,1
DA:370,0
DA:374,1
DA:375,0
DA:382,1
DA:383,1
DA:384,1
DA:385,1
DA:248,0
DA:250,11
DA:251,11
DA:253,11
DA:255,11
DA:256,11
DA:259,0
DA:260,0
DA:265,1
DA:266,0
DA:267,0
DA:268,0
DA:277,1
DA:278,10
DA:279,10
DA:280,10
DA:281,10
DA:282,10
DA:283,10
DA:284,10
DA:304,1
DA:305,0
DA:306,0
DA:307,0
DA:309,0
DA:310,0
DA:314,1
DA:315,0
DA:322,1
DA:323,10
DA:325,10
DA:328,10
DA:344,1
DA:345,8
DA:346,8
DA:347,48
DA:348,48
DA:349,48
DA:350,48
DA:351,18
DA:352,18
DA:354,30
DA:357,0
DA:362,1
DA:363,6
DA:364,6
DA:365,6
DA:366,11
DA:367,0
DA:368,0
DA:372,11
DA:375,10
DA:376,10
DA:379,9
DA:380,9
DA:383,9
DA:386,9
DA:391,9
DA:392,1
DA:393,1
DA:394,1
DA:395,1
DA:396,0
DA:398,1
DA:400,1
DA:408,1
DA:409,0
DA:415,1
DA:416,0
DA:425,1
DA:426,1
DA:427,1
DA:434,1
DA:435,0
LF:128
LH:90
BRDA:37,0,0,1
BRDA:37,0,1,0
BRDA:38,1,0,1
BRDA:38,1,1,0
BRDA:47,2,0,1
BRDA:47,2,1,1
BRDA:99,3,0,5
BRDA:120,4,0,0
BRDA:120,4,1,0
BRDA:126,5,0,0
BRDA:126,5,1,5
BRDA:151,6,0,5
BRDA:151,6,1,5
BRDA:152,7,0,5
BRDA:152,7,1,5
BRDA:155,8,0,5
BRDA:155,8,1,5
BRDA:156,9,0,5
BRDA:156,9,1,5
BRDA:159,10,0,5
BRDA:159,10,1,5
BRDA:160,11,0,5
BRDA:160,11,1,5
BRDA:170,12,0,1
BRDA:170,12,1,0
BRDA:179,13,0,1
BRDA:179,13,1,0
BRDA:192,14,0,0
BRDA:192,14,1,0
BRDA:209,15,0,0
BRDA:209,15,1,0
BRDA:220,16,0,5
BRDA:220,16,1,0
BRDA:222,17,0,0
BRDA:222,17,1,5
BRDA:230,18,0,5
BRDA:230,18,1,0
BRDA:230,18,2,0
BRDA:281,19,0,0
BRDA:281,19,1,0
BRDA:311,20,0,6
BRDA:311,20,1,0
BRDA:311,21,0,6
BRDA:311,21,1,6
BRDA:313,22,0,3
BRDA:313,22,1,3
BRDA:384,23,0,1
BRDA:384,23,1,0
BRDA:395,24,0,0
BRDA:395,24,1,1
BRDA:426,25,0,0
BRDA:426,25,1,1
BRF:52
BRH:31
DA:397,9
DA:400,3
DA:401,3
DA:402,3
DA:404,3
DA:433,1
DA:434,0
DA:438,1
DA:439,0
DA:447,1
DA:448,0
DA:452,1
DA:453,0
DA:457,1
DA:458,0
DA:465,1
DA:466,2
DA:467,2
DA:468,2
DA:476,1
DA:477,2
DA:478,2
DA:479,0
DA:481,2
DA:483,2
DA:491,1
DA:492,0
DA:498,1
DA:499,0
DA:508,1
DA:509,2
DA:510,2
DA:517,1
DA:518,0
LF:155
LH:115
BRDA:38,0,0,11
BRDA:38,0,1,0
BRDA:39,1,0,11
BRDA:39,1,1,0
BRDA:47,2,0,8
BRDA:47,2,1,7
BRDA:48,3,0,8
BRDA:48,3,1,7