slack_message 1.8.1 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94e7433c5374c318cd955ad43f6a02705b62876498253c4e7587a7ba5ae5277f
-  data.tar.gz: 0ca96c1266c9dc55af30c6df7f07e2ea86a64bc5fad99258a10efe10e4127e9b
+  metadata.gz: '008fdfc2e46435b3bb49aae67e30b3ef354ca0c923c935c918088ee25eec7bda'
+  data.tar.gz: 2fe7d85c853361d12f02f58d19e4bef43ffc81d3683ef5f8b3776657eb86c5ae
 SHA512:
-  metadata.gz: 2f4c15c91c6a7741c1f387b820cc36689cd7530233e9582fb3db73407d9f39eb69656a071b65789cd33ec359d5fa1478efe212336a3834202c30f96269885895
-  data.tar.gz: ed86a645c481c0c91510acedc5b0abd2bf3923f9ea33e9a23671db0e107005c07f64a1dfc52f4f5f47f826630712756bd5ce43ddfd06622a10ed24afa7731465
+  metadata.gz: 1c5cc5b43f1813b55b6d1433da88ca661bc692a21785ffad1c2e13c459f0d2b4cb6bbf6251f5e774924a73e8e60f8c2517deaf71a0a1f74f57b2094e822e82ac
+  data.tar.gz: 0bb8d97ef6338703e601bd964405c090823ceded7cfa3045d42618a575397ca057591f6aad1cad6d1a74a7f4b877de11bced2d566424c75b53d80d2ce018cda0

data/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## [Unreleased]
+## [2.2.1] - 2021-11-20
+- Trying to fetch user ID for a string that isn't email-like raises an error.
+- In tests, fetching user IDs is mocked out to prevent network requests.
+- Tightened up and clarified README.
+- Some internal cleanup and restructuring of modules.
+
+## [2.2.0] - 2021-11-20
+- When sending text, it is now possible to mention users and have their user
+  IDs automatically converted using `<email@email.com>` within text nodes.
+- It's now possible to override notification text.
+- Errors received from the Slack API now raise `SlackMessage::ApiError`.
+- Re-exposed a top-level method for getting user IDs, `SlackMessage.user_id`.
+- Raising some better errors when no message payload is present.
+- Using `build` now requires a profile, so configuration must exist.
+
+## [2.1.0] - 2021-11-01
+- Change to use Slack Apps for all profiles. This should allow growth toward
+  updating messages, working with interactive messages etc.
+- As a result, allow custom icons per profile / message.
+- When sending a message, the first `text` block is used for the notification
+  content. Should resolve "this content cannot be displayed".
+- Significant restructuring of README.
+
+## [2.0.0] - 2021-11-01
+- Yeah that was all broken.
+
+## [1.9.0] - 2021-10-27
+- Add many validations so that trying to add e.g. empty text won't succeed.
+  Previously that would be accepted but return `invalid_blocks` from the API.
 
 ## [1.8.1] - 2021-10-08
 - Cleaned that rspec code a bit, added more matchers for real world use.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    slack_message (1.8.0)
+    slack_message (2.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -3,8 +3,7 @@ SlackMessage: a Friendly DSL for Slack
 
 SlackMessage is a wrapper over the [Block Kit
 API](https://app.slack.com/block-kit-builder/) to make it easy to read and
-write messages to slack in your ruby application. It has zero dependencies and
-is built to be opinionated to keep your configuration needs low.
+write messages to slack in your ruby application.
 
 Posting a message to Slack should be this easy:
 
@@ -16,80 +15,107 @@ end
 
 To install, just add `slack_message` to your bundle and you're ready to go.
 
+#### Opinionated Stances
+
+Slack's API has a lot of options available to you! But this gem takes some
+opinionated stances about usage to try to minimize the pain of integrating
+with it. For example:
+
+* SlackMessage has no dependencies. Your lockfile is enough of a mess already.
+* The code to build a message should look a lot like the message itself. Code
+  that is simple to read and understand is a priority.
+* Webhooks are passé. Only Slack Apps are supported now.
+* Unless you request otherwise, text is always rendered using `mrkdwn`. If you
+  want plaintext, you'll need to ask for it. Same for the `emoji` flag.
+* As many API semantics as possible are hidden. For instance, if you post to
+  something that looks like an email address, `slack_message` is going to try
+  to look it up as an email address.
+* A few little hacks on the block syntax, such as adding a `blank_line` (which
+  doesn't exist in the API), or leading spaces.
+* Configuration is kept as simple as possible. But, as much heavy lifting as
+  possible should occur just once via configuration and not on every call.
 
 Usage
 ------------
 
 ### Configuration
 
-To get started, you'll need to configure at least one profile to use to post
-to slack. Get a [Webhook URL](https://slack.com/help/articles/115005265063-Incoming-webhooks-for-Slack)
-from Slack and configure it like this:
+To get started, you'll need to create a Slack App with some appropriate
+permissions.  It used to be possible to use the Webhook API, but that's long
+since been deprecated, and apps are pretty [straightforward to
+create](https://api.slack.com/tutorials/tracks/getting-a-token).
+
+Generally, make sure your token has permissions for `users:read` and `chat:write`.
 
 ```ruby
 SlackMessage.configure do |config|
-  webhook_url = 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
+  api_token = 'xoxb-11111111111-2222222222-33333333333333333'
 
-  config.add_profile(name: 'Slack Notifier', url: webhook_url)
+  config.add_profile(api_token: api_token)
 end
 ```
 
-You should probably keep that webhook in a safe place like `ENV`. If using this
-gem with Rails, place this code in somewhere like
-`config/initializers/slack_message.rb`.
+You should keep your token in a safe place like `ENV`. If using this gem with
+Rails, place this code in somewhere like `config/initializers/slack_message.rb`.
 
 #### Additional Profiles
 
-If you want to post to multiple different webhook addresses (say, if you have
-several different bots that post to different channels as different identities),
-you can configure those profiles as well, by giving each of them a name:
+If your app uses slack messages for several different purposes, it's common to
+want to post to different channels as different names / icons / etc. To do that
+more easily and consistently, you can specify multiple profiles:
 
 ```ruby
 SlackMessage.configure do |config|
+  api_token = 'xoxb-11111111111-2222222222-33333333333333333'
+
   # default profile
-  config.add_profile(name: 'Slack Notifier', url: ENV['SLACK_WEBHOOK_URL'])
+  config.add_profile(api_token: api_token, name: 'Slack Notifier')
 
   # additional profiles (see below for usage)
-  config.add_profile(:prod_alert_bot, name: 'Prod Alert Bot', url: ENV['SLACK_PROD_ALERT_WEBHOOK_URL'])
-  config.add_profile(:sidekiq_bot, name: 'Sidekiq Bot', url: ENV['SLACK_SIDEKIQ_WEBHOOK_URL'])
+  config.add_profile(:prod_alert_bot,
+    name: 'Prod Alert Bot'
+    icon: ':mooseandsquirrel:'
+  )
+  config.add_profile(:sidekiq_bot,
+    api_token: ENV.fetch('SIDEKIQ_SLACK_APP_API_TOKEN'),
+    name: 'Sidekiq Bot',
+  )
 end
 ```
 
-If you frequently ping the same channel with the same bot, and don't want to
-continually specify the channel name, you can specify a default channel and
-post using the `post_as` method. It is otherwise identical to `post_to`, but
-allows you to omit the channel argument:
+A number of parameters are available to make it simpler to use a profile without
+specifying repetitive information. Most all have corresponding options when
+composing a message:
+
+| Config          | Default         | Value                                                           |
+|-----------------|-----------------|-----------------------------------------------------------------|
+| api_token       | None            | Your Slack App API Key.                                         |
+| name            | From Slack App  | The bot name for your message.                                  |
+| icon            | From Slack App  | Profile icon for your message. Specify as :emoji: or image URL. |
+| default_channel | None (optional) | Channel / user to post to by default.                           |
+
+
+Setting a `default_channel` specifically will allow you to use `post_as`, which
+is a convenient shortcut for bots that repeatedly post to one channel as a
+consistent identity:
 
 ```ruby
 SlackMessage.configure do |config|
-  config.add_profile(:prod_alert_bot,
-    name: 'Prod Alert Bot',
-    url: ENV['SLACK_PROD_ALERT_WEBHOOK_URL'],
+  config.add_profile(:red_alert_bot,
+    api_token: ENV.fetch('SLACK_API_TOKEN'),
+    name: 'Red Alerts',
+    icon: ':klaxon:',
     default_channel: '#red_alerts'
   )
 end
 
-SlackMessage.post_as(:prod_alert_bot) do
+SlackMessage.post_as(:red_alert_bot) do
   text ":ambulance: weeooo weeooo something went wrong"
 end
 ```
 
-Note that `post_as` does not allow you to choose a channel (because that's just
-the same as using `post_to`), so you really do have to specify `default_channel`.
-
-#### Configuring User Search
-
-Slack's API no longer allows you to send DMs to users by username. You need to
-look up a user's internal ID and send to that ID. Thankfully, there is a lookup
-by email endpoint for this. If you'd like to post messages to users by their
-email address, you'll need a
-[separate API Token](https://api.slack.com/tutorials/tracks/getting-a-token):
-
-```ruby
-SlackMessage.configure do |config|
-  config.api_token = 'xoxb-11111111111-2222222222-33333333333333333'
-end
-```
+There's no reason you can't use the same API key for several profiles. Profiles
+are most useful to create consistent name / icon setups for apps with many bots.
 
 ### Posting Messages
 
@@ -104,14 +130,12 @@ end
 That's it! SlackMessage will automatically serialize for the API like this:
 
 ```json
-[{"type":"section","text":{"type":"mrkdwn","text":"We did it! :thumbsup:"}}]
+[{"type":"section","text":{"type":"mrkdwn","text":"We did it @here! :thumbsup:"}}]
 ```
 
 Details like remembering that Slack made a mystifying decision to force you to
 request "mrkdwn", or requiring your text to be wrapped into a section are handled
-for you.
-
-Building up messages is meant to be as user-friendly as possible:
+for you. Building up messages is meant to be as user-friendly as possible:
 
 ```ruby
 SlackMessage.build do
@@ -147,20 +171,19 @@ automatically:
 ]
 ```
 
-If you've configured an API key for user search (see above in configuration),
-it's just as easy to send messages directly to users:
+It's just as easy to send messages directly to users. SlackMessage will look for
+targets that are email-addressish, and look them up for you automatically:
 
 ```ruby
 SlackMessage.post_to('hello@joemastey.com') do
-  text "We did it! :thumbsup:"
+  text "You specifically did it! :thumbsup:"
 end
 ```
 
 SlackMessage is able to build all kinds of rich messages for you, and has been
 a real joy to use for the author at least. To understand a bit more about the
-possibilities of blocks, see Slack's [Block Kit
-Builder](https://app.slack.com/block-kit-builder/) to understand the structure
-better. There are lots of options:
+possibilities of blocks, you should play around with Slack's [Block Kit
+Builder](https://app.slack.com/block-kit-builder/). There are lots of options:
 
 ```ruby
 SlackMessage.post_to('#general') do
@@ -184,36 +207,85 @@ SlackMessage.post_to('#general') do
     text "See more here: #{link('result', 'https://google.com')}"
   end
 
-  text ":rocketship: hello@joemastey.com"
+  text ":rocketship: <hello@joemastey.com>"
 
   context ":custom_slack_emoji: An example footer *with some markdown*."
 end
 ```
 
 SlackMessage will compose this into Block Kit syntax and send it on its way!
-For now you'll need to read a bit of the source code to get the entire API. Sorry,
-working on it.
 
 If you've defined multiple profiles in configuration, you can specify which to
-use for your message by specifying their name:
+use for your message by specifying its name:
 
 ```ruby
 SlackMessage.post_to('#general', as: :sidekiq_bot) do
   text ":octagonal_sign: A job has failed permanently and needs to be rescued."
-  link_button "Sidekiq Dashboard", "https://yoursite.com/sidekiq", style: :danger
+
+  link_button "Sidekiq Dashboard", sidekiq_dashboard_url, style: :danger
 end
 ```
 
-You can also use a custom name when sending a message:
+You can also override profile bot details when sending a message:
 
 ```ruby
 SlackMessage.post_to('#general') do
   bot_name "CoffeeBot"
+  bot_icon ":coffee:"
 
   text ":coffee::clock: Time to take a break!"
 end
 ```
 
+#### Notifying Users
+
+There are several supported ways to tag and notify users. Mentioned above, it's
+possible to DM a user by email:
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  text "Hi there!"
+end
+```
+
+You can also mention a user by email within a channel by wrapping their name
+in tags:
+
+```ruby
+SlackMessage.post_to('#general') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  text ":coffee: It's your turn to make coffee <hello@joemastey.com>."
+end
+```
+
+Emails that are not wrapped in tags will be rendered as normal email addresses.
+Additionally, Slack will automatically convert a number of channel names and
+tags you're probably already used to:
+
+```ruby
+SlackMessage.post_to('#general') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  text "@here There's no coffee left! Let #general know when you fix it."
+end
+```
+
+By default, the desktop notification for a message will be the text of the 
+message itself. However, you can customize desktop notifications if you prefer:
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  notification_text "It's a coffee emergency!"
+  text "There's no coffee left!"
+end
+```
+
 ### Testing
 
 You can do some basic testing against SlackMessage, at least if you use RSpec!
@@ -230,13 +302,33 @@ RSpec.configure do |config|
 end
 ```
 
-This will stop API calls for posting messages, and will allow you access to
-some custom matchers:
+This will prevent API calls from leaking in your tests, and will allow you
+access to some custom matchers:
 
 ```ruby
 expect {
   SlackMessage.post_to('#general') { text "foo" }
 }.to post_slack_message_to('#general').with_content_matching(/foo/)
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_as(:schmoebot)
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_as('Schmoe Bot')
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_with_icon(':schmoebot:')
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_with_icon_matching(/gravatar/)
+ 
+expect {
+  SlackMessage.post_to('#general') { text "foo" }
+}.to post_to_slack
 ```
 
 Be forewarned, I'm frankly not that great at more complicated RSpec matchers,
@@ -244,45 +336,32 @@ so I'm guessing there are some bugs. Also, because the content of a message
 gets turned into a complex JSON object, matching against content isn't capable
 of very complicated regexes.
 
-Opinionated Stances
-------------
-
-Slack's API has a lot of options available to you! But this gem takes some
-opinionated stances on how to make use of that API. For instance:
-
-* Unless you request otherwise, text is always rendered using `mrkdwn`. If you
-  want plaintext, you'll need to ask for it.
-* Generally, same goes for the `emoji` flag on almost every text element.
-* It's possible to ask for a `blank_line` in sections, even though that concept
-  isn't real. In this case, a text line containing only an emspace is rendered.
-* It's easy to configure a bot for consistent name / channel use. My previous
-  use of SlackNotifier led to frequently inconsistent names.
-
 What it Doesn't Do
 ------------
 
-This gem is intended to stay fairly simple. Other gems have lots of config
-options and abilities, which is wonderful, but overall complicates usage. If
-you want to add a feature, open an issue on Github first to see if it's likely
-to be merged.
-
-Since this gem was built out of an existing need that _didn't_ include most of
-the block API, I'd be inclined to merge features that sustainably expand the
-DSL to include more of the block API itself.
+This gem is intended to stay simple. Other Slack gems have lots of config
+options and abilities, which makes them powerful, but makes them a pain to use.
+If you want to add a feature, open an issue on Github first to see if it's
+likely to be merged. This gem was built out of an existing need that _didn't_
+include all of the block API, but I'd be inclined to merge features that
+sustainably expand the DSL to include more useful features.
 
-Also, some behaviors that are still planned but not yet added:
+Some behaviors that are still planned but not yet added:
 
 * some API documentation amirite?
-* allow custom http_options in configuration
+* custom http_options in configuration
 * more of BlockKit's options
-* any interactive elements at all (I don't understand them yet)
+* any interactive elements at all
+* editing / updating messages
+* multiple recipients
 * more interesting return types for your message
-* richer text formatting (ul is currently a hack)
+* richer text formatting (for instance, `ul` is currently a hack)
+* more and better organized testing capability
 
 Contributing
 ------------
 
-Contributions are very welcome. Fork, fix, submit pulls.
+Contributions are very welcome. Fork, fix, submit pull.
 
 Contribution is expected to conform to the [Contributor Covenant](https://github.com/jmmastey/slack_message/blob/master/CODE_OF_CONDUCT.md).
 

data/lib/slack_message/api.rb

@@ -2,70 +2,108 @@ require 'net/http'
 require 'net/https'
 require 'json'
 
-class SlackMessage::Api
-  def self.user_id_for(email)
-    token = SlackMessage.configuration.api_token
+module SlackMessage::Api
+  extend self
 
-    uri = URI("https://slack.com/api/users.lookupByEmail?email=#{email}")
-    request = Net::HTTP::Get.new(uri).tap do |req|
-      req['Authorization']  = "Bearer #{token}"
-      req['Content-type']   = "application/json"
+  def user_id_for(email, profile)
+    unless email =~ SlackMessage::EMAIL_PATTERN
+      raise ArgumentError, "Tried to find profile by invalid email address '#{email}'"
     end
 
-    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
-      http.request(request)
-    end
+    response = look_up_user_by_email(email, profile)
 
     if response.code != "200"
-      raise "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
     elsif response.body == ""
-      raise "Received empty 200 response from Slack when looking up user info. Check your API key."
+      raise SlackMessage::ApiError, "Received empty 200 response from Slack when looking up user info. Check your API key."
     end
 
     begin
       payload = JSON.parse(response.body)
     rescue
-      raise "Unable to parse JSON response from Slack API\n#{response.body}"
+      raise SlackMessage::ApiError, "Unable to parse JSON response from Slack API\n#{response.body}"
     end
 
     if payload.include?("error") && payload["error"] == "invalid_auth"
-      raise "Received an error because your authentication token isn't properly configured:\n#{response.body}"
+      raise SlackMessage::ApiError, "Received an error because your authentication token isn't properly configured."
+    elsif payload.include?("error") && payload["error"] == "users_not_found"
+      raise SlackMessage::ApiError, "Couldn't find a user with the email '#{email}'."
     elsif payload.include?("error")
-      raise "Received error response from Slack during user lookup:\n#{response.body}"
+      raise SlackMessage::ApiError, "Received error response from Slack during user lookup:\n#{response.body}"
     end
 
     payload["user"]["id"]
   end
 
-  def self.post(payload, target, profile)
-    profile[:url] = profile[:url]
-
-    uri     = URI.parse(profile[:url])
+  def post(payload, target, profile)
     params  = {
       channel: target,
-      username: profile[:name],
-      blocks: payload
+      username: payload.custom_bot_name || profile[:name],
+      blocks: payload.render,
+      text: payload.custom_notification,
     }
 
-    response = execute_post_form(uri, params, profile[:handle])
+    if params[:blocks].length == 0
+      raise ArgumentError, "Tried to send an entirely empty message."
+    end
+
+    icon = payload.custom_bot_icon || profile[:icon]
+    if icon =~ /^:\w+:$/
+      params[:icon_emoji] = icon
+    elsif icon =~ /^(https?:\/\/)?[0-9a-z]+\.[-_0-9a-z]+/ # very naive regex, I know. it'll be fine.
+      params[:icon_url] = icon
+    elsif !(icon.nil? || icon == '')
+      raise ArgumentError, "Couldn't figure out icon '#{icon}'. Try :emoji: or a URL."
+    end
+
+    response = post_message(profile, params)
+    body  = JSON.parse(response.body)
+    error = body.fetch("error", "")
 
     # let's try to be helpful about error messages
-    if response.body == "invalid_token"
-      raise "Couldn't send slack message because the URL for profile '#{profile[:handle]}' is wrong."
-    elsif response.body == "channel_not_found"
-      raise "Tried to send Slack message to non-existent channel or user '#{target}'"
-    elsif response.body == "missing_text_or_fallback_or_attachments"
-      raise "Tried to send Slack message with invalid payload."
+    if ["token_revoked", "token_expired", "invalid_auth", "not_authed"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't send slack message because the API key for profile '#{profile[:handle]}' is wrong."
+    elsif ["no_permission", "ekm_access_denied"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't send slack message because the API key for profile '#{profile[:handle]}' isn't allowed to post messages."
+    elsif error == "channel_not_found"
+      raise SlackMessage::ApiError, "Tried to send Slack message to non-existent channel or user '#{target}'"
+    elsif error == "invalid_arguments"
+      raise SlackMessage::ApiError, "Tried to send Slack message with invalid payload."
     elsif response.code == "302"
-      raise "Got 302 response while posting to Slack. Check your webhook URL for '#{profile[:handle]}'."
+      raise SlackMessage::ApiError, "Got 302 response while posting to Slack. Check your API key for profile '#{profile[:handle]}'."
     elsif response.code != "200"
-      raise "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
     end
 
     response
   end
 
-  def self.execute_post_form(uri, params, _profile)
-    Net::HTTP.post_form uri, { payload: params.to_json }
+  private
+
+  # mostly for test harnesses
+
+  def look_up_user_by_email(email, profile)
+    uri = URI("https://slack.com/api/users.lookupByEmail?email=#{email}")
+    request = Net::HTTP::Get.new(uri).tap do |req|
+      req['Authorization']  = "Bearer #{profile[:api_token]}"
+      req['Content-type']   = "application/json; charset=utf-8"
+    end
+
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+      http.request(request)
+    end
+  end
+
+  def post_message(profile, params)
+    uri = URI("https://slack.com/api/chat.postMessage")
+    request = Net::HTTP::Post.new(uri).tap do |req|
+      req['Authorization']  = "Bearer #{profile[:api_token]}"
+      req['Content-type']   = "application/json; charset=utf-8"
+      req.body = params.to_json
+    end
+
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+      http.request(request)
+    end
   end
 end

data/lib/slack_message/configuration.rb

@@ -1,9 +1,7 @@
 module SlackMessage::Configuration
-  @@api_token = nil
   @@profiles = {}
 
   def self.reset
-    @@api_token = nil
     @@profiles  = {}
   end
 
@@ -13,39 +11,29 @@ module SlackMessage::Configuration
 
   ###
 
-  def self.api_token=(token)
-    @@api_token = token
-  end
-
-  def self.api_token
-    unless @@api_token.is_a? String
-      raise ArgumentError, "Please set an API token to use API features."
-    end
-
-    @@api_token
-  end
-
-  ###
-
   def self.clear_profiles! # test harness, mainly
     @@profiles = {}
   end
 
-  def self.add_profile(handle = :default, name:, url:, default_channel: nil)
+  def self.add_profile(handle = :default, api_token:, name: nil, icon: nil, default_channel: nil)
     if @@profiles.include?(handle)
       warn "WARNING: Overriding profile '#{handle}' in SlackMessage config"
     end
 
-    @@profiles[handle] = { name: name, url: url, handle: handle, default_channel: default_channel }
+    @@profiles[handle] = {
+      handle: handle,
+      api_token: api_token,
+      name: name,
+      icon: icon,
+      default_channel: default_channel
+    }
   end
 
-  def self.profile(handle, custom_name: nil)
+  def self.profile(handle)
     unless @@profiles.include?(handle)
       raise ArgumentError, "Unknown SlackMessage profile '#{handle}'."
     end
 
-    @@profiles[handle].tap do |profile|
-      profile[:name] = custom_name if !custom_name.nil?
-    end
+    @@profiles[handle]
   end
 end

data/lib/slack_message/dsl.rb

@@ -1,16 +1,21 @@
 class SlackMessage::Dsl
-  attr_reader :body, :default_section, :custom_bot_name
+  attr_reader :body, :default_section, :custom_bot_name, :custom_bot_icon, :profile
+  attr_accessor :custom_notification
 
-  EMSPACE = " " # unicode emspace
+  EMSPACE = " " # unicode emspace, Slack won't compress this
 
-  def initialize(block)
+  def initialize(block, profile)
     # Delegate missing methods to caller scope. Thanks 2008:
     # https://www.dan-manges.com/blog/ruby-dsls-instance-eval-with-delegation
     @caller_self = eval("self", block.binding)
 
-    @body = []
-    @default_section = Section.new
-    @custom_bot_name = nil
+    @body             = []
+    @profile          = profile
+    @default_section  = Section.new(self)
+
+    @custom_bot_name      = nil
+    @custom_bot_icon      = nil
+    @custom_notification  = nil
   end
 
   # allowable top-level entities within a block
@@ -18,7 +23,7 @@ class SlackMessage::Dsl
   def section(&block)
     finalize_default_section
 
-    section = Section.new.tap do |s|
+    section = Section.new(self).tap do |s|
       s.instance_eval(&block)
     end
 
@@ -52,6 +57,12 @@ class SlackMessage::Dsl
   def context(text)
     finalize_default_section
 
+    if text == "" || text.nil?
+      raise ArgumentError, "Cannot create a context block without a value."
+    end
+
+    text = self.enrich_text(text)
+
     @body.push({ type: "context", elements: [{
       type: "mrkdwn", text: text
     }]})
@@ -72,12 +83,20 @@ class SlackMessage::Dsl
 
   # end delegation
 
-  # custom bot name
+  # bot / notification overrides
 
   def bot_name(name)
     @custom_bot_name = name
   end
 
+  def bot_icon(icon)
+    @custom_bot_icon = icon
+  end
+
+  def notification_text(msg)
+    @custom_notification = msg
+  end
+
   # end bot name
 
   def render
@@ -89,6 +108,20 @@ class SlackMessage::Dsl
     @caller_self.send meth, *args, &blk
   end
 
+  # replace emails w/ real user IDs
+  def enrich_text(text_body)
+    text_body.scan(SlackMessage::EMAIL_TAG_PATTERN).each do |email_tag|
+      raw_email = email_tag.gsub(/[><]/, '')
+      user_id   = SlackMessage::Api::user_id_for(raw_email, profile)
+
+      text_body.gsub!(email_tag, "<@#{user_id}>") if user_id
+    rescue SlackMessage::ApiError => e
+      # swallow errors for not-found users
+    end
+
+    text_body
+  end
+
   private
 
   # when doing things that would generate new top-levels, first try
@@ -98,18 +131,25 @@ class SlackMessage::Dsl
       @body.push(default_section.render)
     end
 
-    @default_section = Section.new
+    @default_section = Section.new(self)
   end
 
   class Section
     attr_reader :body
 
-    def initialize
+    def initialize(parent)
+      @parent = parent
       @body = { type: "section" }
       @list = List.new
     end
 
     def text(msg)
+      if msg == "" || msg.nil?
+        raise ArgumentError, "Cannot create a text node without a value."
+      end
+
+      msg = @parent.enrich_text(msg)
+
       if @body.include?(:text)
         @body[:text][:text] << "\n#{msg}"
 
@@ -119,17 +159,21 @@ class SlackMessage::Dsl
     end
 
     def ul(elements)
-      raise Arguments, "please pass an array" unless elements.respond_to?(:map)
-      text(
-        elements.map { |text| "#{EMSPACE}• #{text}" }.join("\n")
-      )
+      raise ArgumentError, "Please pass an array when creating a ul." unless elements.respond_to?(:map)
+
+      msg = elements.map { |text| "#{EMSPACE}• #{text}" }.join("\n")
+      msg = @parent.enrich_text(msg)
+
+      text(msg)
     end
 
     def ol(elements)
-      raise Arguments, "please pass an array" unless elements.respond_to?(:map)
-      text(
-        elements.map.with_index(1) { |text, idx| "#{EMSPACE}#{idx}. #{text}" }.join("\n")
-      )
+      raise ArgumentError, "Please pass an array when creating an ol." unless elements.respond_to?(:map)
+
+      msg = elements.map.with_index(1) { |text, idx| "#{EMSPACE}#{idx}. #{text}" }.join("\n")
+      msg = @parent.enrich_text(msg)
+
+      text(msg)
     end
 
     # styles:  default, primary, danger
@@ -186,6 +230,11 @@ class SlackMessage::Dsl
     end
 
     def list_item(title, value)
+      if value == "" || value.nil?
+        raise ArgumentError, "Can't create a list item for '#{title}' without a value."
+      end
+
+      value = @parent.enrich_text(value)
       @list.add(title, value)
     end
 
@@ -198,7 +247,16 @@ class SlackMessage::Dsl
     end
 
     def render
+      unless has_content?
+        raise ArgumentError, "Can't create a section with no content."
+      end
+
       body[:fields] = @list.render if @list.any?
+
+      if body[:text] && body[:text][:text] && !@parent.custom_notification
+        @parent.notification_text(body[:text][:text])
+      end
+
       body
     end
   end

data/lib/slack_message/rspec.rb

@@ -30,13 +30,34 @@ module SlackMessage::RSpec
   FauxResponse = Struct.new(:code, :body)
 
   def self.included(_)
-    SlackMessage::Api.singleton_class.undef_method(:execute_post_form)
-    SlackMessage::Api.define_singleton_method(:execute_post_form) do |uri, params, profile|
+    SlackMessage::Api.undef_method(:post_message)
+    SlackMessage::Api.define_singleton_method(:post_message) do |profile, params|
       @@listeners.each do |listener|
-        listener.record_call(params.merge(profile: profile, uri: uri))
+        listener.record_call(params.merge(profile: profile))
       end
 
-      return FauxResponse.new('200', 'ok')
+      response = {"ok"=>true,
+       "channel"=>"D12345678",
+       "ts"=>"1635863996.002300",
+       "message"=>
+        {"type"=>"message", "subtype"=>"bot_message",
+        "text"=>"foo",
+        "ts"=>"1635863996.002300",
+        "username"=>"SlackMessage",
+        "icons"=>{"emoji"=>":successkid:"},
+        "bot_id"=>"B1234567890",
+        "blocks"=>
+        [{"type"=>"section",
+          "block_id"=>"hAh7",
+          "text"=>{"type"=>"mrkdwn", "text"=>"foo", "verbatim"=>false}}]}}
+
+      return FauxResponse.new('200', response.to_json)
+    end
+
+    SlackMessage::Api.undef_method(:look_up_user_by_email)
+    SlackMessage::Api.define_singleton_method(:look_up_user_by_email) do |email, profile|
+      response = {"ok"=>true, "user"=>{"id"=>"U5432CBA"}}
+      return FauxResponse.new('200', response.to_json)
     end
   end
 
@@ -102,12 +123,55 @@ module SlackMessage::RSpec
     supports_block_expectations
   end
 
+  # icon matcher
+  matcher :post_slack_message_with_icon do |expected|
+     match do |actual|
+      @instance ||= PostTo.new
+      @instance.with_icon(expected)
+
+      actual.call
+      @instance.enforce_expectations
+    end
+
+    chain :with_content_matching do |content|
+      @instance ||= PostTo.new
+      @instance.with_content_matching(content)
+    end
+
+    failure_message { @instance.failure_message }
+    failure_message_when_negated { @instance.failure_message_when_negated }
+
+    supports_block_expectations
+  end
+
+  matcher :post_slack_message_with_icon_matching do |expected|
+     match do |actual|
+      @instance ||= PostTo.new
+      @instance.with_icon_matching(expected)
+
+      actual.call
+      @instance.enforce_expectations
+    end
+
+    chain :with_content_matching do |content|
+      @instance ||= PostTo.new
+      @instance.with_content_matching(content)
+    end
+
+    failure_message { @instance.failure_message }
+    failure_message_when_negated { @instance.failure_message_when_negated }
+
+    supports_block_expectations
+  end
+
   class PostTo
     def initialize
       @captured_calls = []
       @content = nil
       @channel = nil
       @profile = nil
+      @icon = nil
+      @icon_matching = nil
 
       SlackMessage::RSpec.register_expectation_listener(self)
     end
@@ -120,6 +184,15 @@ module SlackMessage::RSpec
       @channel = channel
     end
 
+    def with_icon(icon)
+      @icon = icon
+    end
+
+    def with_icon_matching(icon)
+      raise ArgumentError unless icon.is_a? Regexp
+      @icon_matching = icon
+    end
+
     def with_content_matching(content)
       raise ArgumentError unless content.is_a? Regexp
       @content = content
@@ -134,8 +207,10 @@ module SlackMessage::RSpec
 
       @captured_calls
         .filter { |call| !@channel || call[:channel] == @channel }
-        .filter { |call| !@profile || [call[:profile], call[:username]].include?(@profile) }
+        .filter { |call| !@profile || [call[:profile][:handle], call[:username]].include?(@profile) }
         .filter { |call| !@content || call.fetch(:blocks).to_s =~ @content }
+        .filter { |call| !@icon || call.fetch(:icon_emoji, call.fetch(:icon_url, '')) == @icon }
+        .filter { |call| !@icon_matching || call.fetch(:icon_emoji, call.fetch(:icon_url, '')) =~ @icon_matching }
         .any?
     end
 
@@ -154,6 +229,10 @@ module SlackMessage::RSpec
         concat << "post a slack message to '#{@channel}'"
       elsif @profile
         concat << "post a slack message as '#{@profile}'"
+      elsif @icon
+        concat << "post a slack message with icon '#{@icon}'"
+      elsif @icon_matching
+        concat << "post a slack message with icon matching '#{@icon_matching.inspect}'"
       else
         concat << "post a slack message"
       end

data/lib/slack_message.rb

@@ -3,6 +3,11 @@ module SlackMessage
   require 'slack_message/api'
   require 'slack_message/configuration'
 
+  EMAIL_TAG_PATTERN = /<[^@ \t\r\n\<]+@[^@ \t\r\n]+\.[^@ \t\r\n]+>/
+  EMAIL_PATTERN = /^\S{1,}@\S{2,}\.\S{2,}$/
+
+  class ApiError < RuntimeError; end
+
   def self.configuration
     Configuration
   end
@@ -11,39 +16,43 @@ module SlackMessage
     configuration.configure(&block)
   end
 
-  def self.user_id_for(email) # spooky undocumented public method 👻
-    Api::user_id_for(email)
+  def self.user_id(email, profile_name = :default)
+    profile = Configuration.profile(profile_name)
+    Api.user_id_for(email, profile)
   end
 
   def self.post_to(target, as: :default, &block)
-    payload = Dsl.new(block).tap do |instance|
+    profile = Configuration.profile(as)
+
+    payload = Dsl.new(block, profile).tap do |instance|
       instance.instance_eval(&block)
     end
 
-    profile = Configuration.profile(as, custom_name: payload.custom_bot_name)
-    target  = user_id_for(target) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
+    target  = Api::user_id_for(target, profile) if target =~ EMAIL_PATTERN
 
-    Api.post(payload.render, target, profile)
+    Api.post(payload, target, profile)
   end
 
   def self.post_as(profile_name, &block)
-    payload = Dsl.new(block).tap do |instance|
-      instance.instance_eval(&block)
-    end
-
-    profile = Configuration.profile(profile_name, custom_name: payload.custom_bot_name)
+    profile = Configuration.profile(profile_name)
     if profile[:default_channel].nil?
       raise ArgumentError, "Sorry, you need to specify a default_channel for profile #{profile_name} to use post_as"
     end
 
+    payload = Dsl.new(block, profile).tap do |instance|
+      instance.instance_eval(&block)
+    end
+
     target  = profile[:default_channel]
-    target  = user_id_for(target) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
+    target  = Api::user_id_for(target, profile) if target =~ EMAIL_PATTERN
 
-    Api.post(payload.render, target, profile)
+    Api.post(payload, target, profile)
   end
 
-  def self.build(&block)
-    Dsl.new(block).tap do |instance|
+  def self.build(profile_name = :default, &block)
+    profile = Configuration.profile(profile_name)
+
+    Dsl.new(block, profile).tap do |instance|
       instance.instance_eval(&block)
     end.send(:render)
   end

data/slack_message.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name        = 'slack_message'
-  gem.version     = "1.8.1"
+  gem.version     = "2.2.1"
   gem.summary     = "A nice DSL for composing rich messages in Slack"
   gem.authors     = ["Joe Mastey"]
   gem.email       = 'hello@joemastey.com'

data/spec/slack_message_spec.rb

@@ -1,21 +1,14 @@
 require 'spec_helper'
 
 RSpec.describe SlackMessage do
-  describe "API convenience" do
-    it "can grab user IDs" do
-      SlackMessage.configure { |c| c.api_token = "asdf" }
-      allow(Net::HTTP).to receive(:start).and_return(
-        double(code: "200", body: '{ "user": { "id": "ABC123" }}')
-      )
-
-      result = SlackMessage.user_id_for("hello@joemastey.com")
-      expect(result).to eq("ABC123")
-    end
-  end
-
   describe "DSL" do
     describe "#build" do
       it "renders some JSON" do
+        SlackMessage.configure do |config|
+          config.clear_profiles!
+          config.add_profile(name: 'default profile', api_token: 'abc123')
+        end
+
         expected_output = [
           { type: "section",
             text: { text: "foo", type: "mrkdwn" }
@@ -32,32 +25,11 @@ RSpec.describe SlackMessage do
   end
 
   describe "configuration" do
-    after do
-      SlackMessage.configuration.reset
-    end
-
-    it "allows you to set an API key" do
-      SlackMessage.configure do |config|
-        config.api_token = "abc123"
-      end
-
-      expect(SlackMessage.configuration.api_token).to eq("abc123")
-    end
-
-    it "raises errors for missing configuration" do
-      SlackMessage.configure do |config|
-        config.api_token = nil
-      end
-
-      expect {
-        SlackMessage.configuration.api_token
-      }.to raise_error(ArgumentError)
-    end
-
     it "lets you add and fetch profiles" do
       SlackMessage.configure do |config|
-        config.add_profile(name: 'default profile', url: 'http://hooks.slack.com/1234/')
-        config.add_profile(:nonstandard, name: 'another profile', url: 'http://hooks.slack.com/1234/')
+        config.clear_profiles!
+        config.add_profile(name: 'default profile', api_token: 'abc123')
+        config.add_profile(:nonstandard, name: 'another profile', api_token: 'abc123')
       end
 
       expect(SlackMessage.configuration.profile(:default)[:name]).to eq('default profile')
@@ -73,7 +45,7 @@ RSpec.describe SlackMessage do
     before do
       SlackMessage.configure do |config|
         config.clear_profiles!
-        config.add_profile(name: 'default profile', url: 'http://hooks.slack.com/1234/')
+        config.add_profile(name: 'default profile', api_token: 'abc123')
       end
     end
 
@@ -97,7 +69,8 @@ RSpec.describe SlackMessage do
 
     it "lets you assert by profile name" do
       SlackMessage.configure do |config|
-        config.add_profile(:schmoebot, name: 'Schmoe', url: 'http://hooks.slack.com/1234/', default_channel: '#schmoes')
+        config.clear_profiles!
+        config.add_profile(:schmoebot, name: 'Schmoe', api_token: 'abc123', icon: ':schmoebot:', default_channel: '#schmoes')
       end
 
       expect {
@@ -113,10 +86,69 @@ RSpec.describe SlackMessage do
       }.to post_slack_message_as('Schmoe').with_content_matching(/foo/)
     end
 
+    it "lets you assert by profile image" do
+      SlackMessage.configure do |config|
+        config.clear_profiles!
+        config.add_profile(:schmoebot, name: 'Schmoe', api_token: 'abc123', icon: ':schmoebot:', default_channel: '#schmoes')
+      end
+
+      expect {
+        SlackMessage.post_as(:schmoebot) { text "foo" }
+      }.to post_slack_message_with_icon(':schmoebot:')
+
+      expect {
+        SlackMessage.post_as(:schmoebot) do
+          bot_icon ':schmalternate:'
+          text "foo"
+        end
+      }.to post_slack_message_with_icon(':schmalternate:')
+
+      expect {
+        SlackMessage.post_as(:schmoebot) do
+          bot_icon 'https://thispersondoesnotexist.com/image'
+          text "foo"
+        end
+      }.to post_slack_message_with_icon_matching(/thisperson/)
+    end
+
+    it "lets you assert notification text" do
+      # TODO :|
+    end
+
     it "can assert more generally too tbh" do
       expect {
         SlackMessage.post_to('#general') { text "foo" }
       }.to post_to_slack.with_content_matching(/foo/)
     end
   end
+
+  describe "API convenience" do
+    let(:profile) { SlackMessage::Configuration.profile(:default) }
+
+    before do
+      SlackMessage.configure do |config|
+        config.clear_profiles!
+        config.add_profile(name: 'default profile', api_token: 'abc123')
+      end
+    end
+
+    it "converts user IDs within text when tagged properly" do
+      allow(SlackMessage::Api).to receive(:user_id_for).and_return('ABC123')
+
+      expect {
+        SlackMessage.post_to('#general') { text("Working: <hello@joemastey.com> ") }
+      }.to post_to_slack.with_content_matching(/ABC123/)
+
+      expect {
+        SlackMessage.post_to('#general') { text("Not Tagged: hello@joemastey.com ") }
+      }.to post_to_slack.with_content_matching(/hello@joemastey.com/)
+
+
+      allow(SlackMessage::Api).to receive(:user_id_for).and_raise(SlackMessage::ApiError)
+
+      expect {
+        SlackMessage.post_to('#general') { text("Not User: <nuffin@nuffin.nuffin>") }
+      }.to post_to_slack.with_content_matching(/\<nuffin@nuffin.nuffin\>/)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_message
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 2.2.1
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-08 00:00:00.000000000 Z
+date: 2021-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec