slack_message 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92b2faa8e8b8118a0e168cef488d64b94255c841d774909647ede3d9a9faf6b
-  data.tar.gz: d494af801908aa9f5cf25141b012df26e23a69f8ef9389c3c8bb580c46641133
+  metadata.gz: 368533ab7e4dae44ffbef5ccf8afef048def96d964a6af64c294c23ba617dfa3
+  data.tar.gz: f9397472bbc5c5db81dd1c9d7715e5015f4ec455948e7a29afbb11ef8c8a3d01
 SHA512:
-  metadata.gz: 6fceee6aeb36f7fc6b855c1ce90f647b67ce480c78e62ec2fe45bbfc347e6c9efa6ca910804c51b0edb12321953d96014ac137572d2140328109444f68512ca4
-  data.tar.gz: a9fe4697d85ac2f91197a39dacc46d1740c251f8472dcb91e8ba2132caac5c9f029cb5f88894f39542e1436ce554562d87108661863c2574655e64c866c5115e
+  metadata.gz: 5cce143a95d508694221f1c667428f850ce7aa537e73f61c1869498b68a5751afe2ac386215b96702a1a27bcad3758c474ba09870a1cd7a31a7c33a17ebd4d53
+  data.tar.gz: 7f81e1876f231899588b174c87c4a0a3ca3bcbc4057216092311b300cff7d23d6541083b5e481e811795042538e2e6713b1a9f5eb5f6eba345e79960335cad91

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # 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

data/Gemfile.lock

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

data/README.md

@@ -30,8 +30,8 @@ opinionated stances on how to make use of that API. For instance:
   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 should be as simple as possible. But as much work as possible
-  should be moved from callers into configuration.
+* 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
 ------------
@@ -238,6 +238,55 @@ SlackMessage.post_to('#general') do
 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!
@@ -301,12 +350,12 @@ expand the DSL to include more useful features.
 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 (probably related to the above)
+* more interesting return types for your message
 * richer text formatting (for instance, `ul` is currently a hack)
 
 Contributing

data/lib/slack_message/api.rb

@@ -15,21 +15,23 @@ 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"]
@@ -40,9 +42,13 @@ class SlackMessage::Api
       channel: target,
       username: payload.custom_bot_name || profile[:name],
       blocks: payload.render,
-      text: payload.notification_text,
+      text: payload.custom_notification,
     }
 
+    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
@@ -58,17 +64,17 @@ class SlackMessage::Api
 
     # let's try to be helpful about error messages
     if ["token_revoked", "token_expired", "invalid_auth", "not_authed"].include?(error)
-      raise "Couldn't send slack message because the API key for profile '#{profile[:handle]}' is wrong."
+      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 "Couldn't send slack message because the API key for profile '#{profile[:handle]}' isn't allowed to post messages."
+      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 "Tried to send Slack message to non-existent channel or user '#{target}'"
+      raise SlackMessage::ApiError, "Tried to send Slack message to non-existent channel or user '#{target}'"
     elsif error == "invalid_arguments"
-      raise "Tried to send Slack message with invalid payload."
+      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 API key for profile '#{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

data/lib/slack_message/dsl.rb

@@ -1,19 +1,21 @@
 class SlackMessage::Dsl
-  attr_reader :body, :default_section, :custom_bot_name, :custom_bot_icon
-  attr_accessor :notification_text
+  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(self)
-    @custom_bot_name = nil
-    @custom_bot_icon = nil
-    @notification_text = 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
@@ -56,9 +58,11 @@ class SlackMessage::Dsl
     finalize_default_section
 
     if text == "" || text.nil?
-      raise ArgumentError, "tried to create a context block without a value"
+      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
     }]})
@@ -79,7 +83,7 @@ class SlackMessage::Dsl
 
   # end delegation
 
-  # custom bot name
+  # bot / notification overrides
 
   def bot_name(name)
     @custom_bot_name = name
@@ -89,6 +93,10 @@ class SlackMessage::Dsl
     @custom_bot_icon = icon
   end
 
+  def notification_text(msg)
+    @custom_notification = msg
+  end
+
   # end bot name
 
   def render
@@ -100,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
@@ -123,9 +147,11 @@ class SlackMessage::Dsl
 
     def text(msg)
       if msg == "" || msg.nil?
-        raise ArgumentError, "tried to create text node without a value"
+        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}"
 
@@ -135,19 +161,21 @@ class SlackMessage::Dsl
     end
 
     def ul(elements)
-      raise ArgumentError, "please pass an array" unless elements.respond_to?(:map)
+      raise ArgumentError, "Please pass an array when creating a ul." unless elements.respond_to?(:map)
 
-      text(
-        elements.map { |text| "#{EMSPACE}• #{text}" }.join("\n")
-      )
+      msg = elements.map { |text| "#{EMSPACE}• #{text}" }.join("\n")
+      msg = @parent.enrich_text(msg)
+
+      text(msg)
     end
 
     def ol(elements)
-      raise ArgumentError, "please pass an array" unless elements.respond_to?(:map)
+      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(
-        elements.map.with_index(1) { |text, idx| "#{EMSPACE}#{idx}. #{text}" }.join("\n")
-      )
+      text(msg)
     end
 
     # styles:  default, primary, danger
@@ -205,9 +233,10 @@ class SlackMessage::Dsl
 
     def list_item(title, value)
       if value == "" || value.nil?
-        raise ArgumentError, "can't create a list item for '#{title}' without a value"
+        raise ArgumentError, "Can't create a list item for '#{title}' without a value."
       end
 
+      value = @parent.enrich_text(value)
       @list.add(title, value)
     end
 
@@ -220,10 +249,14 @@ 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.notification_text
-        @parent.notification_text = body[:text][:text]
+      if body[:text] && body[:text][:text] && !@parent.custom_notification
+        @parent.notification_text(body[:text][:text])
       end
 
       body

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,35 +13,43 @@ module SlackMessage
     configuration.configure(&block)
   end
 
+  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)
     target  = Api::user_id_for(target, profile) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
 
     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)
     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  = Api::user_id_for(target, profile) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
 
     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     = "2.1.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,31 +1,14 @@
 require 'spec_helper'
 
 RSpec.describe SlackMessage do
-  describe "API convenience" do
-    before do
-      SlackMessage.configure do |config|
-        config.add_profile(name: 'default profile', api_token: 'abc123')
-      end
-    end
-
-    after do
-      SlackMessage.configuration.reset
-    end
-
-    it "can grab user IDs" do
-      profile = SlackMessage::Configuration.profile(:default)
-      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
-  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" }
@@ -42,12 +25,9 @@ RSpec.describe SlackMessage do
   end
 
   describe "configuration" do
-    after do
-      SlackMessage.configuration.reset
-    end
-
     it "lets you add and fetch profiles" do
       SlackMessage.configure do |config|
+        config.clear_profiles!
         config.add_profile(name: 'default profile', api_token: 'abc123')
         config.add_profile(:nonstandard, name: 'another profile', api_token: 'abc123')
       end
@@ -141,4 +121,43 @@ RSpec.describe SlackMessage do
       }.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: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-02 00:00:00.000000000 Z
+date: 2021-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec