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

+ Also updated some interfaces and docs

README.md

@@ -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.

coverage/lcov.info

 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