slack_message 1.8.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 455886af2c6e775c37db510da7d5003abd131711107e9a18af2e10a714f9c154
-  data.tar.gz: '029d322491f3e63df60cd61eb2c6528132cce722a4ca0fa2db47fd790702fa04'
+  metadata.gz: 368533ab7e4dae44ffbef5ccf8afef048def96d964a6af64c294c23ba617dfa3
+  data.tar.gz: f9397472bbc5c5db81dd1c9d7715e5015f4ec455948e7a29afbb11ef8c8a3d01
 SHA512:
-  metadata.gz: dd4bc35189956140e5409d1d2e325e2cb6b9423e23fbcb6f81399281b10e4447b8c1bed8e8447f7dac59b5282e9c39b4907231225f0858abe6116fe9419b9269
-  data.tar.gz: d91718d74c17d0b1c79485de6311a70a579b1f80916c4328afa813800735b12d29e1069cfdc1721f1954839a6b55d25c0fa292ed41d02350ac0c1665a3475aa2
+  metadata.gz: 5cce143a95d508694221f1c667428f850ce7aa537e73f61c1869498b68a5751afe2ac386215b96702a1a27bcad3758c474ba09870a1cd7a31a7c33a17ebd4d53
+  data.tar.gz: 7f81e1876f231899588b174c87c4a0a3ca3bcbc4057216092311b300cff7d23d6541083b5e481e811795042538e2e6713b1a9f5eb5f6eba345e79960335cad91

data/CHANGELOG.md

@@ -1,9 +1,34 @@
 # Changelog
 
-## [Unreleased]
+## [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.
 
 ## [1.8.0] - 2021-10-07
-- Added the ability to test in RSpec
+- Added the ability to test in RSpec.
 
 ## [1.7.1] - 2021-10-06
 - Fixed literally a syntax issue.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    slack_message (1.7.1)
+    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,105 @@ 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 on how to make use of that API. For instance:
+
+* No dependencies. Your lockfile is enough of a mess already.
+* 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 +128,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 +169,21 @@ 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:"
+user_email = 'hello@joemastey.com'
+
+SlackMessage.post_to(user_email) do
+  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
@@ -195,25 +218,75 @@ For now you'll need to read a bit of the source code to get the entire API. Sorr
 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 clickable 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!"
+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!
@@ -237,6 +310,26 @@ some custom matchers:
 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 +337,31 @@ 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.
+to be merged. This gem was built out of an existing need that _didn't_ include
+most 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)
 
 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

@@ -3,13 +3,11 @@ require 'net/https'
 require 'json'
 
 class SlackMessage::Api
-  def self.user_id_for(email)
-    token = SlackMessage.configuration.api_token
-
+  def self.user_id_for(email, profile)
     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"
+      req['Authorization']  = "Bearer #{profile[:api_token]}"
+      req['Content-type']   = "application/json; charset=utf-8"
     end
 
     response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
@@ -17,55 +15,84 @@ class SlackMessage::Api
     end
 
     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])
     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 }
+  # mostly test harness
+  def self.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
+
+  private_class_method :post_message
 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
 
-  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,22 @@ class SlackMessage::Dsl
     @caller_self.send meth, *args, &blk
   end
 
+  EMAIL_TAG_PATTERN = /<[^@ \t\r\n\<]+@[^@ \t\r\n]+\.[^@ \t\r\n]+>/
+
+  # replace emails w/ real user IDs
+  def enrich_text(text_body)
+    text_body.scan(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 +133,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 +161,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 +232,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 +249,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

@@ -4,6 +4,15 @@ require 'rspec/mocks'
 # Honestly, this code is what happens when you do not understand the RSpec
 # custom expectation API really at all, but you really want to create your
 # matcher. This code is soo baaad.
+#
+# We override API calls by entirely replacing the low-level API method. Then we
+# use our overridden version to capture and record calls. When someone creates
+# a new expectation, an object is created, so we allow that object to register
+# itself to receive notification when a slack message _would have_ been posted.
+#
+# Then once the expectation is fulfilled, that class unregisters itself so that
+# it can be cleaned up properly.
+#
 
 module SlackMessage::RSpec
   extend RSpec::Matchers::DSL
@@ -21,16 +30,32 @@ 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.singleton_class.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
   end
 
+  # w/ channel
   matcher :post_slack_message_to do |expected|
     match do |actual|
       @instance ||= PostTo.new
@@ -40,9 +65,91 @@ module SlackMessage::RSpec
       @instance.enforce_expectations
     end
 
-    chain :with_content_matching do |content_expectation|
+    chain :with_content_matching do |content|
       @instance ||= PostTo.new
-      @instance.with_content_matching(content_expectation)
+      @instance.with_content_matching(content)
+    end
+
+    failure_message { @instance.failure_message }
+    failure_message_when_negated { @instance.failure_message_when_negated }
+
+    supports_block_expectations
+  end
+
+  # no channel
+  matcher :post_to_slack do |expected|
+    match do |actual|
+      @instance ||= PostTo.new
+
+      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
+
+  # name / profile matcher
+  matcher :post_slack_message_as do |expected|
+     match do |actual|
+      @instance ||= PostTo.new
+      @instance.with_profile(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
+
+  # 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 }
@@ -54,8 +161,11 @@ module SlackMessage::RSpec
   class PostTo
     def initialize
       @captured_calls = []
-      @content_expectation = nil
+      @content = nil
       @channel = nil
+      @profile = nil
+      @icon = nil
+      @icon_matching = nil
 
       SlackMessage::RSpec.register_expectation_listener(self)
     end
@@ -68,41 +178,64 @@ module SlackMessage::RSpec
       @channel = channel
     end
 
-    def with_content_matching(content_expectation)
-      raise ArgumentError unless content_expectation.is_a? Regexp
-      @content_expectation = content_expectation
+    def with_icon(icon)
+      @icon = icon
     end
 
-    def enforce_expectations
-      SlackMessage::RSpec.unregister_expectation_listener(self)
-      matching_messages.any? { |msg| body_matches_expectation?(msg.fetch(:blocks)) }
+    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
     end
 
-    def matching_messages
-      @captured_calls.select { |c| c[:channel] == @channel }
+    def with_profile(profile)
+      @profile = profile
     end
 
-    def body_matches_expectation?(sent)
-      return true unless @content_expectation
+    def enforce_expectations
+      SlackMessage::RSpec.unregister_expectation_listener(self)
 
-      sent.to_s =~ @content_expectation
+      @captured_calls
+        .filter { |call| !@channel || call[:channel] == @channel }
+        .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
 
     def failure_message
-      if @content_expectation
-        "expected block to post slack message to '#{@channel}' with content matching #{@content_expectation.inspect}"
-      else
-        "expected block to post slack message to '#{@channel}'"
-      end
+      "expected block to #{failure_expression}"
     end
 
-    # TODO: does content_matching even make sense for negated test?
     def failure_message_when_negated
-      if @content_expectation
-        "expected block not to post slack message to '#{@channel}' with content matching #{@content_expectation.inspect}"
+      "expected block not to #{failure_expression}"
+    end
+
+    def failure_expression
+      concat = []
+
+      if @channel
+        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
-        "expected block not to post slack message to '#{@channel}'"
+        concat << "post a slack message"
+      end
+
+      if @content
+        concat << "with content matching #{@content.inspect}"
       end
+
+      concat.join " "
     end
   end
 end

data/lib/slack_message.rb

@@ -3,6 +3,8 @@ module SlackMessage
   require 'slack_message/api'
   require 'slack_message/configuration'
 
+  class ApiError < RuntimeError; end
+
   def self.configuration
     Configuration
   end
@@ -11,39 +13,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 =~ /^\S{1,}@\S{2,}\.\S{2,}$/
 
-    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 =~ /^\S{1,}@\S{2,}\.\S{2,}$/
 
-    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.0"
+  gem.version     = "2.2.0"
   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 = "abc123"
-      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
 
@@ -87,12 +59,105 @@ RSpec.describe SlackMessage do
       }.to post_slack_message_to('#general').with_content_matching(/foo/)
     end
 
-    it "is not stateful" do
+    it "resets state properly" do
       expect {
         SlackMessage.post_to('#general') { text "foo" }
       }.to post_slack_message_to('#general')
 
       expect { }.not_to post_slack_message_to('#general')
     end
+
+    it "lets you assert by profile name" 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_to('#schmoes')
+
+      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').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 "can grab user IDs" do
+      allow(Net::HTTP).to receive(:start).and_return(
+        double(code: "200", body: '{ "user": { "id": "ABC123" }}')
+      )
+
+      result = SlackMessage::Api.user_id_for("hello@joemastey.com", profile)
+      expect(result).to eq("ABC123")
+    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.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-07 00:00:00.000000000 Z
+date: 2021-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec