_ = require "lodash" Promise = require "bluebird" {RtmClient, WebClient} = require "@slack/client" SlackFormatter = require "./formatter" class SlackClient ###* # Number used for limit when making paginated requests to Slack Web API list methods # @private ### @PAGE_SIZE = 100 ###* # Number of milliseconds which the information returned by `conversations.info` is considered to be valid. The default # value is 5 minutes, and it can be customized by setting the `HUBOT_SLACK_CONVERSATION_CACHE_TTL_MS` environment # variable. Setting this number higher will reduce the number of requests made to the Web API, which may be helpful if # your Hubot is experiencing rate limiting errors. However, setting this number too high will result in stale data # being referenced, and your scripts may experience errors related to channel info (like the name) being incorrect # after a user changes it in Slack. # @private ### @CONVERSATION_CACHE_TTL_MS = if process.env.HUBOT_SLACK_CONVERSATION_CACHE_TTL_MS then parseInt(process.env.HUBOT_SLACK_CONVERSATION_CACHE_TTL_MS, 10) else (5 * 60 * 1000) ###* # @constructor # @param {Object} options - Configuration options for this SlackClient instance # @param {string} options.token - Slack API token for authentication # @param {Object} [options.rtm={}] - Configuration options for owned RtmClient instance # @param {Object} [options.rtmStart={}] - Configuration options for RtmClient#start() method # @param {boolean} [options.noRawText=false] - Deprecated: All SlackTextMessages (subtype of TextMessage) will contain # both the formatted text property and the rawText property # @param {Robot} robot - Hubot robot instance ### constructor: (options, @robot) -> # Client initialization # NOTE: the recommended initialization options are `{ dataStore: false, useRtmConnect: true }`. However the # @rtm.dataStore property is publically accessible, so the recommended settings cannot be used without breaking # this object's API. The property is no longer used internally. @rtm = new RtmClient options.token, options.rtm @web = new WebClient options.token, { maxRequestConcurrency: 1 } @robot.logger.debug "RtmClient initialized with options: #{JSON.stringify(options.rtm)}" @rtmStartOpts = options.rtmStart || {} # Message formatter # NOTE: the SlackFormatter class is deprecated. However the @format property is publicly accessible, so it cannot # be removed without breaking this object's API. The property is no longer used internally. @format = new SlackFormatter(@rtm.dataStore, @robot) # Map to convert bot user IDs (BXXXXXXXX) to user representations for events from custom # integrations and apps without a bot user @botUserIdMap = { "B01": { id: "B01", user_id: "USLACKBOT" } } # Map to convert conversation IDs to conversation representations @channelData = {} # Event handling # NOTE: add channel join and leave events @rtm.on "message", @eventWrapper, this @rtm.on "reaction_added", @eventWrapper, this @rtm.on "reaction_removed", @eventWrapper, this @rtm.on "presence_change", @eventWrapper, this @rtm.on "member_joined_channel", @eventWrapper, this @rtm.on "member_left_channel", @eventWrapper, this @rtm.on "file_shared", @eventWrapper, this @rtm.on "user_change", @updateUserInBrain, this @eventHandler = undefined ###* # Open connection to the Slack RTM API # # @public ### connect: -> @robot.logger.debug "RtmClient#start() with options: #{JSON.stringify(@rtmStartOpts)}" @rtm.start(@rtmStartOpts) ###* # Set event handler # # @public # @param {SlackClient~eventHandler} callback ### onEvent: (callback) -> @eventHandler = callback if @eventHandler != callback ###* # DEPRECATED Attach event handlers to the RTM stream # @public # @deprecated This method is being removed without a replacement in the next major version. ### on: (type, callback) -> @robot.logger.warning "SlackClient#on() is a deprecated method and will be removed in the next major version " + "of hubot-slack. It is recommended not to use event handlers on the Slack clients directly. Please file an " + "issue for any specific event type you need.\n" + "Issue tracker: \n" + "Event type: #{type}\n" @rtm.on(type, callback) ###* # Disconnect from the Slack RTM API # # @public ### disconnect: -> @rtm.disconnect() # NOTE: removal of event listeners possibly does not belong in disconnect, because they are not added in connect. @rtm.removeAllListeners() ###* # Set a channel's topic # # @public # @param {string} conversationId - Slack conversation ID # @param {string} topic - new topic ### setTopic: (conversationId, topic) -> @robot.logger.debug "SlackClient#setTopic() with topic #{topic}" # The `conversations.info` method is used to find out if this conversation can have a topic set # NOTE: There's a performance cost to making this request, which can be avoided if instead the attempt to set the # topic is made regardless of the conversation type. If the conversation type is not compatible, the call would # fail, which is exactly the outcome in this implementation. @web.conversations.info(conversationId) .then (res) => conversation = res.channel if !conversation.is_im && !conversation.is_mpim return @web.conversations.setTopic(conversationId, topic) else @robot.logger.debug "Conversation #{conversationId} is a DM or MPDM. " + "These conversation types do not have topics." .catch (error) => @robot.logger.error "Error setting topic in conversation #{conversationId}: #{error.message}" ###* # Send a message to Slack using the Web API. # # This method is usually called when a Hubot script is sending a message in response to an incoming message. The # response object has a `send()` method, which triggers execution of all response middleware, and ultimately calls # `send()` on the Adapter. SlackBot, the adapter in this case, delegates that call to this method; once for every item # (since its method signature is variadic). The `envelope` is created by the Hubot Response object. # # This method can also be called when a script directly calls `robot.send()` or `robot.adapter.send()`. That bypasses # the execution of the response middleware and directly calls into SlackBot#send(). In this case, the `envelope` # parameter is up to the script. # # The `envelope.room` property is intended to be a conversation ID. Even when that is not the case, this method will # makes a reasonable attempt at sending the message. If the property is set to a public or private channel name, it # will still work. When there's no `room` in the envelope, this method will fallback to the `id` property. That # affordance allows scripts to use Hubot User objects, Slack users (as obtained from the response to `users.info`), # and Slack conversations (as obtained from the response to `conversations.info`) as possible envelopes. In the first # two cases, envelope.id` will contain a user ID (`Uxxx` or `Wxxx`). Since Hubot runs using a bot token (`xoxb`), # passing a user ID as the `channel` argument to `chat.postMessage` (with `as_user=true`) results in a DM from the bot # user (if `as_user=false` it would instead result in a DM from slackbot). Leaving `as_user=true` has no effect when # the `channel` argument is a conversation ID. # # NOTE: This method no longer accepts `envelope.room` set to a user name. Using it in this manner will result in a # `channel_not_found` error. # # @public # @param {Object} envelope - a Hubot Response envelope # @param {Message} [envelope.message] - the Hubot Message that was received and generated the Response which is now # being used to send an outgoing message # @param {User} [envelope.user] - the Hubot User object representing the user who sent `envelope.message` # @param {string} [envelope.room] - a Slack conversation ID for where `envelope.message` was received, usually an # alias of `envelope.user.room` # @param {string} [envelope.id] - a Slack conversation ID similar to `envelope.room` # @param {string|Object} message - the outgoing message to be sent, can be a simple string or a key/value object of # optional arguments for the Slack Web API method `chat.postMessage`. ### send: (envelope, message) -> room = envelope.room || envelope.id if not room? @robot.logger.error "Cannot send message without a valid room. Envelopes should contain a room property set to " + "a Slack conversation ID." return @robot.logger.debug "SlackClient#send() room: #{room}, message: #{message}" options = as_user: true, link_names: 1, # when the incoming message was inside a thread, send responses as replies to the thread # NOTE: consider building a new (backwards-compatible) format for room which includes the thread_ts. # e.g. "#{conversationId} #{thread_ts}" - this would allow a portable way to say the message is in a thread thread_ts: envelope.message?.thread_ts if typeof message isnt "string" @web.chat.postMessage(room, message.text, _.defaults(message, options)) .catch (error) => @robot.logger.error "SlackClient#send() error: #{error.message}" else @web.chat.postMessage(room, message, options) .catch (error) => @robot.logger.error "SlackClient#send() error: #{error.message}" ###* # Fetch users from Slack API using pagination # # @public # @param {SlackClient~usersCallback} callback ### loadUsers: (callback) -> # some properties of the real results are left out because they are not used combinedResults = { members: [] } pageLoaded = (error, results) => return callback(error) if error # merge results into combined results combinedResults.members.push(member) for member in results.members if results?.response_metadata?.next_cursor # fetch next page @web.users.list({ limit: SlackClient.PAGE_SIZE, cursor: results.response_metadata.next_cursor }, pageLoaded) else # pagination complete, run callback with results callback(null, combinedResults) @web.users.list({ limit: SlackClient.PAGE_SIZE }, pageLoaded) ###* # Fetch user info from the brain. If not available, call users.info # @public ### fetchUser: (userId) -> # User exists in the brain - retrieve this representation return Promise.resolve(@robot.brain.data.users[userId]) if @robot.brain.data.users[userId]? # User is not in brain - call users.info # The user will be added to the brain in EventHandler @web.users.info(userId).then((r) => @updateUserInBrain(r.user)) ###* # Fetch bot user info from the bot -> user map # @public ### fetchBotUser: (botId) -> return Promise.resolve(@botUserIdMap[botId]) if @botUserIdMap[botId]? # Bot user is not in mapping - call bots.info @web.bots.info(bot: botId).then((r) => r.bot) ###* # Fetch conversation info from conversation map. If not available, call conversations.info # @public ### fetchConversation: (conversationId) -> # Current date minus time of expiration for conversation info expiration = Date.now() - SlackClient.CONVERSATION_CACHE_TTL_MS # Check whether conversation is held in client's channelData map and whether information is expired return Promise.resolve(@channelData[conversationId].channel) if @channelData[conversationId]?.channel? and expiration < @channelData[conversationId]?.updated # Delete data from map if it's expired delete @channelData[conversationId] if @channelData[conversationId]? # Return conversations.info promise @web.conversations.info(conversationId).then((r) => if r.channel? @channelData[conversationId] = { channel: r.channel, updated: Date.now() } r.channel ) ###* # Will return a Hubot user object in Brain. # User can represent a Slack human user or bot user # # The returned user from a message or reaction event is guaranteed to contain: # # id {String}: Slack user ID # slack.is_bot {Boolean}: Flag indicating whether user is a bot # name {String}: Slack username # real_name {String}: Name of Slack user or bot # room {String}: Slack channel ID for event (will be empty string if no channel in event) # # This may be called as a handler for `user_change` events or to update a # a single user with its latest SlackUserInfo object. # # @private # @param {SlackUserInfo|SlackUserChangeEvent} event_or_user - an object containing information about a Slack user # that should be updated in the brain ### updateUserInBrain: (event_or_user) -> # if this method was invoked as a `user_change` event handler, unwrap the user from the event user = if event_or_user.type == 'user_change' then event_or_user.user else event_or_user # create a full representation of the user in the shape we persist for Hubot brain based on the parameter # all top-level properties of the user are meant to be shared across adapters newUser = id: user.id name: user.name real_name: user.real_name slack: {} # don't create keys for properties that have no value, because the empty value will become authoritative newUser.email_address = user.profile.email if user.profile?.email? # all "non-standard" keys of a user are namespaced inside the slack property, so they don't interfere with other # adapters (in case this hubot switched between adapters) for key, value of user newUser.slack[key] = value # merge any existing representation of this user already stored in the brain into the new representation if user.id of @robot.brain.data.users for key, value of @robot.brain.data.users[user.id] # the merge strategy is to only copy over data for keys that do not exist in the new representation # this means the entire `slack` property is treated as one value unless key of newUser newUser[key] = value # remove the existing representation and write the new representation to the brain delete @robot.brain.data.users[user.id] @robot.brain.userForId user.id, newUser ###* # Processes events to fetch additional data or rearrange the shape of an event before handing off to the eventHandler # # @private # @param {SlackRtmEvent} event - One of any of the events listed in with RTM enabled. ### eventWrapper: (event) -> if @eventHandler # fetch full representations of the user, bot, and potentially the item_user. fetches = {} fetches.user = @fetchUser event.user if event.user fetches.bot = @fetchBotUser event.bot_id if event.bot_id fetches.item_user = @fetchUser event.item_user if event.item_user # after fetches complete... Promise.props(fetches) .then (fetched) => # start augmenting the event with the fetched data event.item_user = fetched.item_user if fetched.item_user # assigning `event.user` properly depends on how the message was sent if fetched.user # messages sent from human users, apps with a bot user and using the bot token, and slackbot have the user # property: this is preferred if its available event.user = fetched.user # fetched.bot will exist and be false if bot_id in @botUserIdMap # but is from custom integration or app without bot user else if fetched.bot # fetched.bot is user representation of bot since it exists in botToUserMap if @botUserIdMap[event.bot_id] event.user = fetched.bot # bot_id exists on all messages with subtype bot_message # these messages only have a user_id property if sent from a bot user (xoxb token). therefore # the above assignment will not happen for all messages from custom integrations or apps without a bot user else if fetched.bot.user_id? return @web.users.info(fetched.bot.user_id).then((res) => event.user = res.user @botUserIdMap[event.bot_id] = res.user return event ) else # bot doesn't have an associated user id @botUserIdMap[event.bot_id] = false event.user = {} else event.user = {} return event # once the event is fully populated... .then (fetchedEvent) => # hand the event off to the eventHandler try @eventHandler(fetchedEvent) catch error then @robot.logger.error "An error occurred while processing an RTM event: #{error.message}." # handle fetch errors .catch (error) => @robot.logger.error "Incoming RTM message dropped due to error fetching info for a property: #{error.message}." ###* # A handler for all incoming Slack events that are meaningful for the Adapter # # @callback SlackClient~eventHandler # @param {Object} event # @param {SlackUserInfo} event.user # @param {string} event.channel ### ###* # Callback that recieves a list of users # # @callback SlackClient~usersCallback # @param {Error|null} error - an error if one occurred # @param {Object} results # @param {Array} results.members ### if SlackClient.CONVERSATION_CACHE_TTL_MS is NaN throw new Error('HUBOT_SLACK_CONVERSATION_CACHE_TTL_MS must be a number. It could not be parsed.') module.exports = SlackClient