@slack/client - npm Package Compare versions

Comparing version 3.15.0 to 3.16.0

docs/_pages/rtm_client.md

@@ -12,2 +12,3 @@ ---
     - title: Listening for message subtypes
+    - title: Subscribing to presence updates
     - title: Handling other events
@@ -192,4 +193,104 @@ - title: Data stores
 
-## Handling other events
+### Subscribing to presence updates
 
+Polite people try not to inundate their colleages with messages when they know they are offline.
+We can teach a bot the same ettiquette by subscribing to
+[presence and status information](https://api.slack.com/docs/presence-and-status) for the
+users with which it interacts.
+
+You may not need to subscribe to presence updates if your bot is okay with fetching the user's
+status on-demand using the
+`[WebClient#users.getPresence()]({{ site.baseurl }}{% link _reference/UsersFacet.md %}#UsersFacet+getPresence)`
+method.
+
+If you do prefer to subscribe to presence updates, each time the client connects, your bot needs to
+send a list of user IDs using the `subscribePresence(userIds)` method. The `userIds` argument is an
+array of user IDs and the list must be complete -- any user IDs not included are unsubscribed from
+your bot.
+
+You can get more efficient `presence_change` events by using the `batch_presence_aware` option
+while connecting. If you set the option to `true` your bot will receive `presence_change` events
+with a `users` property that contains an array of user IDs (instead of a `user` property with a
+single user ID). See more about the event: <https://api.slack.com/events/presence_change>.
+
+The following example shows how a bot would keep a timecard for users to record their active
+time or away time.
+
+```javascript
+const { RtmClient, CLIENT_EVENTS, RTM_EVENTS, WebClient } = require('@slack/client');
+
+// An access token (from your Slack app or custom integration - usually xoxb)
+const token = process.env.SLACK_TOKEN;
+
+// Initialize the RTM client. The dataStore option must be set to false.
+const rtm = new RtmClient(token, {
+  dataStore: false,
+  useRtmConnect: true,
+});
+
+// Initialize the Web client
+const web = new WebClient(token);
+
+// Timecard data - In order for this data to survive a restart, it should be backed by a database.
+// Keys: user IDs (string)
+// Values: presence updates (array of { timestamp: number, presence: 'away'|'active' })
+const timecards = new Map();
+const getTrackedUsers = () => Array.from(timecards.keys())
+const updateTimecard = (userId, presence) => {
+  if (!timecards.has(userId)) {
+    timecards.set(userId, []);
+  }
+  const userRecord = timecards.get(userId);
+  userRecord.push({ timestamp: Date.now(), presence });
+}
+const removeTimecard = (userId) => timecards.delete(userId);
+
+// Timecard data is tracked for users in a pre-defined channel
+const timeTrackingChannelId = 'C123456';
+
+
+// RTM event handling
+rtm.on(CLIENT_EVENTS.RTM.RTM_CONNECTION_OPEN, () => {
+  rtm.subscribePresence(getTrackedUsers());
+});
+
+// See: https://api.slack.com/events/presence_change
+rtm.on(RTM_EVENTS.PRESENCE_CHANGE, (event) => {
+  event.users.forEach(userId => updateTimecard(userId, event.presence));
+});
+
+// See: https://api.slack.com/events/member_joined_channel
+rtm.on('member_joined_channel', (event) => {
+  if (event.channel === timeTrackingChannelId) {
+    // When a user joins, get that user's current presence in order to update the timecard
+    web.users.getPresence(event.user)
+      .then(resp => {
+        updateTimecard(event.user, resp.presence);
+        // Update subscriptions
+        rtm.subscribePresence(getTrackedUsers());
+      })
+      .catch(console.error);
+  }
+});
+
+// See: https://api.slack.com/events/member_left_channel
+rtm.on('member_left_channel', (event) => {
+  if (event.channel === timeTrackingChannelId) {
+    // When a user leaves, the timecard records are deleted
+    removeTimecard(event.user);
+    // Update subscriptions
+    rtm.subscribePresence(getTrackedUsers());
+  }
+});
+
+// Start the connecting process
+rtm.start({
+  batch_presence_aware: true,
+});
+```
+
+---
+
+### Handling other events
+
 Anything that happens in a Slack workspace, and that is visible to the bot (_i.e._ happens in a
@@ -196,0 +297,0 @@ channel to which the bot belongs) is communicated as an event as well. For a complete list of other

docs/_pages/web_client.md

@@ -229,6 +229,4 @@ ---
 const web = new WebClient(token, {
-  retryConfig: {
-    // Allow up to 10 requests to be in-flight at a time
-    maxRequestConcurrency: 10,
-  },
+  // Allow up to 10 requests to be in-flight at a time
+  maxRequestConcurrency: 10,
 });
@@ -235,0 +233,0 @@ ```

docs/_reference/RTMClient.md

@@ -19,3 +19,3 @@ ---
     * [._createFacets()](#RTMClient+_createFacets)
-    * [.start(opts)](#RTMClient+start)
+    * [.start([opts])](#RTMClient+start)
     * ~~[.login()](#RTMClient+login)~~
@@ -108,3 +108,3 @@ * [.nextMessageId()](#RTMClient+nextMessageId)
 
-### rtmClient.start(opts)
+### rtmClient.start([opts])
 Begin an RTM session.
@@ -114,5 +114,6 @@
 
-| Param | Type |
-| --- | --- |
-| opts | <code>object</code> | 
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [opts] | <code>object</code> |  |  |
+| [opts.batch_presence_aware] | <code>boolean</code> | <code>false</code> | Opt into receiving fewer `presence_change` events that can contain many users. Instead of the event containing one `user` property {string}, it would contain a `users` property {string[]}. This option is not compatible with using the `dataStore`, you must initialize the RTM client object with the `dataStore: false` option. |
 
@@ -119,0 +120,0 @@ <a name="RTMClient+login"></a>

docs/_reference/UsersFacet.md

@@ -13,2 +13,3 @@ ---
     * [.list([opts], [optCb])](#UsersFacet+list)
+    * [.lookupByEmail(email, [opts], [optCb])](#UsersFacet+lookupByEmail)
     * [.setActive([optCb])](#UsersFacet+setActive)
@@ -72,2 +73,16 @@ * [.setPresence(presence, [optCb])](#UsersFacet+setPresence)
 
+<a name="UsersFacet+lookupByEmail"></a>
+
+### usersFacet.lookupByEmail(email, [opts], [optCb])
+Find a user with an email address.
+
+**Kind**: instance method of <code>[UsersFacet](#UsersFacet)</code>  
+**See**: [users.lookupByEmail](https://api.slack.com/methods/users.lookupByEmail)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| email | <code>?</code> | An email address belonging to a user in the workspace |
+| [opts] | <code>Object</code> |  |
+| [optCb] | <code>function</code> | Optional callback, if not using promises. |
+
 <a name="UsersFacet+setActive"></a>
@@ -74,0 +89,0 @@

lib/clients/rtm/client.js

@@ -249,3 +249,7 @@ /**
  * Begin an RTM session.
- * @param {object} opts
+ * @param {object} [opts]
+ * @param {boolean} [opts.batch_presence_aware=false] - Opt into receiving fewer `presence_change`
+ * events that can contain many users. Instead of the event containing one `user` property {string},
+ * it would contain a `users` property {string[]}. This option is not compatible with using the
+ * `dataStore`, you must initialize the RTM client object with the `dataStore: false` option.
  */
@@ -252,0 +256,0 @@ RTMClient.prototype.start = function start(opts) {

lib/clients/transports/request.js

@@ -9,2 +9,3 @@ /**
 var defaults = require('lodash').defaults;
+var cloneDeep = require('lodash').cloneDeep;
 var request = require('request');
@@ -68,3 +69,4 @@
   return function _requestOptionsTransport(args, cb) {
-    var requestArgs = defaults(options, getRequestTransportArgs(args));
+    var instanceOptions = cloneDeep(options);
+    var requestArgs = defaults(instanceOptions, getRequestTransportArgs(args));
     request.post(requestArgs, partial(handleRequestTranportRes, cb));
@@ -71,0 +73,0 @@ };

lib/clients/web/facets/users.js

@@ -11,2 +11,3 @@ var isFunction = require('lodash').isFunction;
  *   - list: {@link https://api.slack.com/methods/users.list|users.list}
+ *   - lookupByEmail: {@link https://api.slack.com/methods/users.lookupByEmail|users.lookupByEmail}
  *   - setActive: {@link https://api.slack.com/methods/users.setActive|users.setActive}
@@ -103,2 +104,19 @@ *   - setPresence: {@link https://api.slack.com/methods/users.setPresence|users.setPresence}
 /**
+ * Find a user with an email address.
+ * @see {@link https://api.slack.com/methods/users.lookupByEmail|users.lookupByEmail}
+ *
+ * @param {?} email - An email address belonging to a user in the workspace
+ * @param {Object=} opts
+ * @param {function=} optCb Optional callback, if not using promises.
+ */
+UsersFacet.prototype.lookupByEmail = function lookupByEmail(email, opts, optCb) {
+  var requiredArgs = {
+    email: email
+  };
+
+  return this.makeAPICall('users.lookupByEmail', requiredArgs, opts, optCb);
+};
+
+
+/**
  * Marks a user as active.
@@ -105,0 +123,0 @@ * @see {@link https://api.slack.com/methods/users.setActive|users.setActive}

package.json

 {
   "name": "@slack/client",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "description": "A library for creating a Slack client",
@@ -5,0 +5,0 @@ "main": "./index",

README.md

@@ -9,3 +9,3 @@ # Node Slack SDK
 
-So you want to build a Slack app with Node.js? We've got you covered. {{ site.product_name }} is aimed at making
+So you want to build a Slack app with Node.js? We've got you covered. This package is aimed at making
 building Slack apps ridiculously easy. This package will help you build on all aspects of the Slack platform,
@@ -36,4 +36,4 @@ from dropping notifications in channels to fully interactive bots.
 |--------------|:--------:|:--------:|---------------------|-------------------|
-| Web API      | ⬆️        | ⬜️       | `@slack/client`     | [Guide](https://slackapi.github.io/node-slack-sdk/web_client) |
-| RTM API      | ⬆️        | ⬇️        | `@slack/client`     | [Guide](https://slackapi.github.io/node-slack-sdk/rtm_client) |
+| Web API      | ⬆️        | ⬜️       | `@slack/client`     | [Guide](https://slackapi.github.io/node-slack-sdk/web_api) |
+| RTM API      | ⬆️        | ⬇️        | `@slack/client`     | [Guide](https://slackapi.github.io/node-slack-sdk/rtm_api) |
 | Incoming Webhooks | ⬆️   | ⬜️       | `@slack/client`     | [Guide](https://slackapi.github.io/node-slack-sdk/incoming_webhook) |
@@ -44,3 +44,3 @@ | Events API   | ⬜️       | ⬇️        | `@slack/events-api` | [README](https://github.com/slackapi/node-slack-events-api) |
 **Just starting out?** We suggest starting at the
-[Getting Started guide](https://slackapi.github.io/node-slack-sdk/getting_started.md) which will walk you
+[Getting Started guide](https://slackapi.github.io/node-slack-sdk/getting_started) which will walk you
 through building your first Slack app using Node.js.
@@ -116,5 +116,5 @@
 
-// The client will emit an RTM.RTM_CONNECTION_OPEN the connection is ready for
+// The client will emit an RTM.RTM_CONNECTION_OPENED the connection is ready for
 // sending and recieving messages
-rtm.on(CLIENT_EVENTS.RTM.RTM_CONNECTION_OPEN, () => {
+rtm.on(CLIENT_EVENTS.RTM.RTM_CONNECTION_OPENED, () => {
   console.log(`Ready`);
@@ -121,0 +121,0 @@ });

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1035547

increased by87.34%

Number of package files

415

increased by86.94%

Lines of code

15826

increased by86.17%

Worsened metrics

Number of low supply chain risk alerts

14

increased by27.27%

Number of medium supply chain risk alerts

4

increased by100%

No dependency changes