slack_message 2.2.2 → 3.0.0

data/docs/03_message_dsl.md

@@ -0,0 +1,283 @@
+### The Message DSL
+
+A pretty good number of the elements available in BlockKit are usable in SlackMessage. There are also a few elements that haven't been implemented in the official API, but are too useful to be missing.
+
+#### Basic Text
+
+While BlockKit officially requires that any elements are contained within a section element, that requirement is relaxed in SlackMessage. If you don't specify a section, one will silently be created to encapsulate your code. That's the secret behind the most basic messages in these docs.
+
+```ruby
+SlackMessage.build do
+  text "couldn't be easier"
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"couldn't be easier"}
+# }]
+```
+
+This is equivalent to the more verbose version with a declared section.
+
+```ruby
+SlackMessage.build do
+  section do
+    text "could be easier"
+  end
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"could be easier"}
+# }]
+```
+
+Text elements are the most basic type of element. Adding multiple text calls
+will add a newline between text calls, which will cause a line break
+appropriately.
+
+```ruby
+SlackMessage.build do
+  text "one fish, two fish"
+  text "red fish, blue fish"
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"one fish, two fish\nred fish, blue fish"}
+# }]
+```
+
+Slack uses a [faux-markdown syntax called
+mrkdwn](https://api.slack.com/reference/surfaces/formatting#basics), which you
+may be familiar with by typing in the Slack app itself. The API will
+automatically render mrkdwn appropriately.
+
+```ruby
+SlackMessage.build do
+  text "*Favorite Colors*"
+  text "_John_: ~red~ actually blue."
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"*Favorite Colors*\n_John_: ~red~ actually blue."}}]
+```
+
+Rendering emoji in messages is possible using either a) real unicode emoji in
+your message, or b) using the `:emojiname:` syntax, which supports any emoji
+that would work in your Slack app itself, including custom emoji.
+
+```ruby
+SlackMessage.build do
+  text ":shipit_squirrel:🚀 time to gooo :tada:"
+end
+
+# => [{:type=>"section",
+#   :text=>{:type=>"mrkdwn", :text=>":shipit_squirrel:🚀 time to gooo :tada:"}
+# }]
+```
+
+To add a link using Slack's non-markdown link syntax, use the `link` helper
+method interpolated into a text element. Using the `link` helper as its own
+element won't work, as the method simply returns a string that has to be
+included into a text element specifically.
+
+```ruby
+SlackMessage.build do
+  text "Your #{link('build', 'https://google.com')} is ready."
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"Your <https://google.com|build> is ready."}
+# }]
+```
+
+While the API squishes whitespace (much in the same way HTML does), it may
+sometimes be useful to add a blank line between text _without_ adding a new
+section to your message. To do so, use the pseudo-element `blank_line`.
+
+```ruby
+SlackMessage.build do
+  text "don't let this line"
+  blank_line
+  text "touch this line."
+end
+
+# => => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"don't let this line\n \ntouch this line."}
+# }]
+```
+
+Note that between the two newlines in the above example is a unicode emspace,
+which the API will respect as a line worth rendering.
+
+#### Buttons
+
+BlockKit allows you to specify a button to the right of a section / block. That
+button will be aligned outside the normal space for a section, and is meant to
+link out of the app. To create one of these, use the `link_button` helper.
+
+```ruby
+SlackMessage.build do
+  text "Your daily stats are ready @here"
+  link_button "Stats Dashboard", stats_dashboard_url
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"Your daily stats are ready @here"},
+# :accessory=>
+#  {:type=>"button",
+#   :url=>"http://yoursite.com/stats_dashboard",
+#   :text=>{:type=>"plain_text", :text=>"Stats Dashboard", :emoji=>true},
+#   :style=>:primary}}]
+```
+
+Slack allows three styles for buttons: `default`, `primary`, and `danger`.
+These correspond to gray, green and red buttons respectively. If not specified,
+SlackMessage will use the `primary` style for buttons. I get that this could be
+confusing when there is a default style, but in my experience, a colorful button
+is way more common.
+
+You can override the button style by specifying the style with your link button.
+
+```ruby
+SlackMessage.build do
+  text "A job has failed catastrophically!"
+  link_button "Sidekiq Dashboard", sidekiq_dashboard_url, style: :danger
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"A job has failed catastrophically!"},
+# :accessory=>
+#  {:type=>"button",
+#   :url=>"https://yoursite.com/sidekiq",
+#   :text=>{:type=>"plain_text", :text=>"Sidekiq Dashboard", :emoji=>true},
+#   :style=>:danger}}]
+```
+
+#### Lists and List Items
+
+- list_item, ul, ol
+
+### Including Multiple Sections
+
+Adding more sections is trivial. Simply declare each section and it will be
+separated in the rendered message. This can often occur when looping.
+
+```ruby
+SlackMessage.build do
+  pet_types.each do |type, breeds|
+    section do
+      text "*#{type}:* #{breeds.join(", ")}"
+    end
+  end
+end
+```
+
+It can also be useful to add a visual divider (similar to a `hr` in HTML)
+between sections. To add one of these, use the `divider` helper. You can also
+add a divider at the end of all the sections, but it often looks silly.
+
+```ruby
+SlackMessage.build do
+  section do
+    text "*Topsiders:* Emily, Elsie, Derick"
+  end
+
+  divider
+
+  section do
+    text "*Undergrounders:* Kristina, Lauren, Different Emily"
+  end
+end
+
+# => [
+#  {:type=>"section", :text=>{:type=>"mrkdwn", :text=>"*Topsiders:* Emily, Elsie, Derick"}},
+#  {:type=>"divider"},
+#  {:type=>"section", :text=>{:type=>"mrkdwn", :text=>"*Undergrounders:* Kristina, Lauren, Different Emily"}}
+# ]
+```
+
+Note that a divider can only occur between sections, not within a single
+section. Because of how implicit sections are built, it may look like this works
+for simple messages. You may have troubles when you start adding more
+complicated elements to your messages.
+
+### Images
+- image, accessory_image
+
+### Footers (Context)
+
+Slack allows you to add a small additional piece of text to your message, which
+will be rendered in italics and small text. It can support both links and emoji,
+and is useful for providing minor details for your message.
+
+```ruby
+SlackMessage.build do
+  text "New coffee complaints have been added."
+  context "this complaint added by #{link('Joe Mastey', 'hello@joemastey.com')}."
+end
+
+# => [{:type=>"section",
+#      :text=>{:type=>"mrkdwn", :text=>"New coffee complaints have been added."}
+#     },
+#     {:type=>"context", :elements=>
+#       [{:type=>"mrkdwn",
+#         :text=>"this complaint added by <hello@joemastey.com|Joe Mastey>."
+#     }]
+# }]
+```
+
+Context does not belong to a section, and is per-message, not per-section.
+Specifying more than one context will simply overwrite previous calls.
+
+### Bot Customization
+
+By default - and with scheduled messages - Slack will use the name and icon of
+the Slack app whose API key you configured. As seen before, it's
+possible to override those default names and icons in configuration. However, it
+can also be customized per-message.
+
+```ruby
+SlackMessage.build do
+  bot_icon ":sad_robot:"
+  bot_name "BadNewsBuildBot"
+
+  text "The build is broken. @here"
+end
+
+# => [{:type=>"section", :text=>{:type=>"mrkdwn", :text=>"The build is broken. @here"}}]
+```
+
+Notice that the bot details aren't shown in the output of the `build` command.
+To view the changes these methods cause, use `debug` mode.
+
+The `bot_icon` can be specified as either an emoji (`:example:`), or a URL
+pointing to an image (`http://mysite.com/shipit.png`). Any other value seems to
+cause an error.
+
+### Custom Notification Text
+
+For users who have notifications turned on, Slack will provide a small message
+preview when you send them a message. By default, this preview will take the
+first several words from your message.
+
+However, you can specify some custom notification text to be shown to the user.
+This text supports basic emoji and formatting, but nothing complicated.
+
+```ruby
+SlackMessage.build do
+  notification_text "Having issues with the build. :ohnoes:"
+
+  text "The build is broken. The error message was 'undefined method round for NilClass'"
+
+# => [{:type=>"section",
+# :text=>
+#  {:type=>"mrkdwn",
+#   :text=>"The build is broken. The error message was 'undefined method round for NilClass'"}}]
+end
+```
+
+Again notice that notification text is not set within the blocks themselves, so
+you will need to enable debugging to see how it changes what is sent to the API.
+
+---
+
+Next: [Editing Messages](https://jmmastey.github.io/slack_message/04_editing_messages)

data/docs/04_editing_messages.md

@@ -0,0 +1,88 @@
+### Updating a Previous Message
+
+After you've posted a message, you may want to edit it later. Interactive bots,
+for instance, may want to repeatedly update a message.
+
+Posting will always return an object representing your posted message.
+
+```ruby
+message = SlackMessage.post_to('#general') do
+  text "Getting ready..."
+end
+```
+
+Then, you can use that response object to go back and rewrite the message a
+little or a lot.
+
+```ruby
+SlackMessage.update(message) do
+  text "Done!"
+end
+```
+
+The new message contents will be built and updated via the API. To give an
+example, you could alert slack to a job status by updating your original
+message.
+
+
+```ruby
+class SomeWorker < ApplicationWorker
+  def perform
+    post_started_status
+
+    # ... perform work here
+
+    post_finished_status
+  end
+
+  private
+
+  def post_started_status
+    @message = SlackMessage.post_as(:job_worker) do
+      text "Beginning upload."
+    end
+  end
+
+  def post_finished_status
+    SlackMessage.update(@message) do
+      text "Finished upload! @here come and get it."
+      link_button "See Results", uploaded_data_url
+    end
+  end
+end
+```
+
+#### Storing Response Objects for Later
+
+Since updates are likely to occur after you've long since finished posting the
+original message, you'll need to persist the message response somehow until you
+need to update it later. As one option, you could serialize the response object
+for later.
+
+```ruby
+# initially
+message = SlackMessage.post_to('#general') do
+  text "Starting..."
+end
+redis_connection.set(self.message_cache_key, Marshal.dump(message))
+
+
+# later
+message = Marshal.load(redis_connection.get(self.message_cache_key))
+SlackMessage.update(message) do
+  text "Finished!"
+end
+```
+
+#### Updating Scheduled Messages
+
+Sadly, there's currently no way to edit a scheduled message. You'll receive an
+error if you attempt to call `update` on a scheduled message.
+
+See the [API documentation for
+chat.update](https://api.slack.com/methods/chat.update) for more information on
+updating messages.
+
+---
+
+Next: [Deleting Messages](https://jmmastey.github.io/slack_message/05_deleting_messages)

data/docs/05_deleting_messages.md

@@ -0,0 +1,45 @@
+### Deleting Messages
+
+Deleting a message is much like editing a message, only simpler. Just like when
+you edit a message, you'll need a reference to the message you posted.
+
+*Important Note: It's not possible to delete a message sent directly to a user.
+It's also not possible to delete a scheduled message once it's already posted.
+Don't send anything you don't want your boss to read.*
+
+```ruby
+message = SlackMessage.post_to('#general') do
+  text "Testing: #{SLACK_SECRET_KEY}"
+end
+```
+
+Now you can simply call the `delete` method to make up for your mistakes.
+
+```ruby
+SlackMessage.delete(message)
+```
+
+As with editing a message, it's possible to persist messages to redis / your
+database and remove them using the timestamp and channel of your message.
+
+```ruby
+# initially
+message = SlackMessage.post_to('#general') do
+  text "Testing: #{SLACK_SECRET_KEY}"
+end
+redis_connection.set(self.message_cache_key, Marshal.dump(message))
+
+
+# later
+message = Marshal.load(redis_connection.get(self.message_cache_key))
+SlackMessage.delete(message)
+```
+
+See the [API documentation for
+chat.delete](https://api.slack.com/methods/chat.delete) or
+[chat.deleteScheduledMessage](https://api.slack.com/methods/chat.deleteScheduledMessage)
+for more information on deleting messages.
+
+---
+
+Next: [Mentions / Notifying Users](https://jmmastey.github.io/slack_message/06_notifying_users)

data/docs/06_notifying_users.md

@@ -0,0 +1,62 @@
+## Mentions / Notifying Users
+
+There are several supported ways to tag and notify users. As mentioned
+initially, it's possible to DM a user by their account 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
+```
+
+#### Using @channel or @here
+
+Not really a feature, but Slack will respect usage of `@here` and `@channel`.
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "Hey @channel, don't forget to submit your drink requests."
+end
+```
+
+---
+
+Next: [Testing](https://jmmastey.github.io/slack_message/07_testing)

data/docs/07_testing.md

@@ -0,0 +1,49 @@
+## Testing
+
+You can do some basic testing against SlackMessage, at least if you use RSpec!
+You'll need to require and include the testing behavior in your spec_helper
+file.
+
+```ruby
+require 'slack_message/rspec'
+
+RSpec.configure do |config|
+  include SlackMessage::RSpec
+
+  # your other spec_helper config
+end
+```
+
+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,
+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.

data/docs/index.md

@@ -0,0 +1,7 @@
+* [Configuration](https://jmmastey.github.io/slack_message/01_configuration)
+* [Posting a Message](https://jmmastey.github.io/slack_message/02_posting_a_message)
+* [The SlackMessage DSL](https://jmmastey.github.io/slack_message/03_message_dsl)
+* [Editing Messages](https://jmmastey.github.io/slack_message/04_editing_messages)
+* [Deleting Messages](https://jmmastey.github.io/slack_message/05_deleting_messages)
+* [Mentions / Notifying Users](https://jmmastey.github.io/slack_message/06_notifying_users)
+* [Testing](https://jmmastey.github.io/slack_message/07_testing)

data/lib/slack_message/api.rb

@@ -35,7 +35,7 @@ module SlackMessage::Api
     payload["user"]["id"]
   end
 
-  def post(payload, target, profile)
+  def post(payload, target, profile, time)
     params  = {
       channel: target,
       username: payload.custom_bot_name || profile[:name],
@@ -56,10 +56,24 @@ module SlackMessage::Api
       raise ArgumentError, "Couldn't figure out icon '#{icon}'. Try :emoji: or a URL."
     end
 
+    if !time.nil?
+      params[:post_at] = time.to_i
+
+      if payload.custom_bot_name || payload.custom_bot_icon
+        raise ArgumentError, "Sorry, setting an image / emoji icon for scheduled messages isn't supported."
+      end
+    end
+
+    if SlackMessage::Configuration.debugging?
+      warn params.inspect
+    end
+
     response = post_message(profile, params)
     body  = JSON.parse(response.body)
     error = body.fetch("error", "")
 
+    # TODO: if a scheduled message w/ a short timer is "time_in_past", warn the user?
+
     # let's try to be helpful about error messages
     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."
@@ -75,6 +89,51 @@ module SlackMessage::Api
       raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
     end
 
+    SlackMessage::Response.new(response, profile[:handle])
+  end
+
+  def update(payload, message, profile)
+    params  = {
+      channel: message.channel,
+      ts: message.timestamp,
+      blocks: payload.render,
+      text: payload.custom_notification # TODO: ???
+    }
+
+    if params[:blocks].length == 0
+      raise ArgumentError, "Tried to send an entirely empty message."
+    end
+
+    if SlackMessage::Configuration.debugging?
+      warn params.inspect
+    end
+
+    response = update_message(profile, params)
+    body  = JSON.parse(response.body)
+    error = body.fetch("error", "")
+
+    # TODO: error messaging
+
+    SlackMessage::Response.new(response, profile[:handle])
+  end
+
+  def delete(message, profile)
+    params = if message.scheduled?
+      {
+        channel: message.channel,
+        scheduled_message_id: message.scheduled_message_id,
+      }
+    else
+      {
+        channel: message.channel,
+        ts: message.timestamp,
+      }
+    end
+
+    response = delete_message(profile, params)
+
+    # TODO error handling (incl for already scheduled-and-sent messages)
+
     response
   end
 
@@ -84,6 +143,7 @@ module SlackMessage::Api
 
   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"
@@ -95,7 +155,44 @@ module SlackMessage::Api
   end
 
   def post_message(profile, params)
-    uri = URI("https://slack.com/api/chat.postMessage")
+    uri = if params.has_key?(:post_at)
+      URI("https://slack.com/api/chat.scheduleMessage")
+    else
+      URI("https://slack.com/api/chat.postMessage")
+    end
+
+    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
+
+  def update_message(profile, params)
+    uri = URI("https://slack.com/api/chat.update")
+
+    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
+
+  def delete_message(profile, params)
+    uri = if params.has_key?(:scheduled_message_id)
+      URI("https://slack.com/api/chat.deleteScheduledMessage")
+    else
+      URI("https://slack.com/api/chat.delete")
+    end
+
     request = Net::HTTP::Post.new(uri).tap do |req|
       req['Authorization']  = "Bearer #{profile[:api_token]}"
       req['Content-type']   = "application/json; charset=utf-8"

data/lib/slack_message/configuration.rb

@@ -1,8 +1,10 @@
 module SlackMessage::Configuration
   @@profiles = {}
+  @@debug = false
 
   def self.reset
-    @@profiles  = {}
+    @@profiles = {}
+    @@debug = false
   end
 
   def self.configure
@@ -36,4 +38,12 @@ module SlackMessage::Configuration
 
     @@profiles[handle]
   end
+
+  def self.debug
+    @@debug = true
+  end
+
+  def self.debugging?
+    @@debug
+  end
 end