slack_message 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b97efc9f2b80be4ee01c89d4c82aab83bb79983077ec8bfa87f0026ea5387f37
-  data.tar.gz: ae251f82220f9c15e45d3065f4e8cd84f5ad913c630a48d6cf9713df33b41b34
+  metadata.gz: 62f8b7feb3289a37b79cb887dc4e7846c037a8c72290138afe611682a066a884
+  data.tar.gz: 73e391d721ace67ad31ae69b7a17eae3578d4f85a2bcd111a5cb1966b68c85cd
 SHA512:
-  metadata.gz: c2e5a3f499fe2e73f245ff2163284f73825f3d051c4cc06aee03c39184eb01e22d6ce5d426f1dde77a0f89e6eacd1764b3a49b1f0548a368490588a7dc0bd757
-  data.tar.gz: d2417ed29a6b0e3b88133e9e679a965104d2b9030945d7241af106b54dabc471190d73902f4a4bceae02a469f24eeeeb6e95d91f1b8c9817dc0f69ee41a6524d
+  metadata.gz: cb28febfda107047351955825d1cd84dafdf553147b9f0101573944f3d5290c6d3e84a4d1190e63888f6c8ba851ac70da9eb774f1a01a04372d19520b7df8779
+  data.tar.gz: 3438883916204aec8a16a8dfa80b52506d4f640fc69161ad6e8efea1b5a136e97fc15f8b990c2529f3bbfb1f4380a989a0827cbe8f810af08a42bf3a2b6df382

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [3.0.0] - 2021-12-19
+- Return a more structured object from successful message sends.
+- Add the ability to edit or delete a message.
+- Complete overhaul of docs because they were too large.
+
 ## [2.4.0] - 2021-12-13
 - Add ability to schedule messages, plus some guard rails around that.
 - Add ability to debug by logging out the total set of params sent to the API.

data/README.md

@@ -48,6 +48,11 @@ SlackMessage.post_to('#general') do
 end
 ```
 
+### The Docs
+
+You'll find much more information about how to use SlackMessage by visiting
+[the docs](https://jmmastey.github.io/slack_message).
+
 #### Opinionated Stances
 
 This gem is intended to stay simple. Other Slack gems have lots of config
@@ -75,8 +80,10 @@ Some behaviors that are still planned but not yet added:
 * multiple recipients: https://api.slack.com/methods/conversations.open
 * more interesting return types for your message
 * richer text formatting (for instance, `ul` is currently a hack)
+* more mrkdwn syntax, like quotes or code blocks
 * more and better organized testing capability
 * posting ephemeral messages: https://api.slack.com/methods/chat.postEphemeral
+* some Rspec test harness for scheduled messages, editing, deleting (probably going to need a test overhaul)
 
 Contributing
 ------------

data/docs/01_configuration.md

@@ -0,0 +1,116 @@
+## Getting Started / Configuration
+
+To get started sending messages, you'll first 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 _at least_ `users:read` and
+`chat:write`. Then, define a default profile for SlackMessage to use for
+posting.
+
+```ruby
+SlackMessage.configure do |config|
+  api_token = 'xoxb-11111111111-2222222222-33333333333333333'
+
+  config.add_profile(api_token: api_token)
+end
+```
+
+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 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(api_token: api_token, name: 'Slack Notifier')
+
+  # additional profiles (see below for usage)
+  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
+```
+
+A number of parameters are available to make it simpler to use a profile
+without specifying repetitive information. You can generally also specify this
+information on a per-message basis.
+
+| 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(:red_alert_bot,
+    api_token: ENV.fetch('SLACK_API_TOKEN'),
+    name: 'Red Alerts',
+    icon: ':klaxon:',
+    default_channel: '#red_alerts'
+  )
+end
+
+SlackMessage.post_as(:red_alert_bot) do
+  text ":ambulance: weeooo weeooo something went wrong"
+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.
+
+### Debug Mode
+
+If you'd like to get more information about the messages you send, you can set
+SlackMessage to debug mode.
+
+```ruby
+SlackMessage.configure do |config|
+  config.debug
+end
+```
+
+You will now see warnings detailing all params sent to the API.
+
+```ruby
+  {
+    :channel=>"#general",
+    :username=>"Builds",
+    :blocks=>[
+      {:type=>"section", :text=>{
+        :type=>"mrkdwn",
+        :text=>"Build Stability is Looking Ruff :dog:"
+      }}
+    ],
+    :text=>"Build Issues",
+    :post_at=>1639421171,
+  }
+```
+
+Note this includes data that is not included in `SlackMessage.build`.
+
+---
+
+Next: [Posting a Message](https://jmmastey.github.io/slack_message/02_posting_a_message)

data/docs/02_posting_a_message.md

@@ -0,0 +1,134 @@
+## Posting Messages
+
+As mentioned at the outset, posting a message to Slack is dang easy.
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "We did it @here! :thumbsup:"
+end
+```
+
+That's it! SlackMessage will automatically serialize for the API.
+
+```json
+[{"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.
+
+```ruby
+SlackMessage.build do
+  text "haiku are easy"
+  text "but sometimes they don't make sense"
+  text "refrigerator"
+
+  context "- unknown author"
+end
+```
+
+SlackMessage will combine your text declarations and add any necessary wrappers
+automatically.
+
+```json
+[
+  {
+    "type": "section",
+    "text": {
+      "type": "mrkdwn",
+      "text": "haiku are easy\nbut sometimes they don't make sense\nrefrigerator"
+    }
+  },
+  {
+    "type": "context",
+    "elements": [
+      {
+        "type": "mrkdwn",
+        "text": "- unknown author"
+      }
+    ]
+  }
+]
+```
+
+### Direct Messages
+
+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 "You specifically did it! :thumbsup:"
+end
+```
+
+SlackMessage will compose this into Block Kit syntax and send it on its way!
+
+### Multiple Profiles
+
+If you've defined multiple profiles in configuration, you can specify which to
+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", sidekiq_dashboard_url, style: :danger
+end
+```
+
+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
+```
+
+Finally, if your profile specifies a `default_channel`, you can also post with
+the `post_as` shorthand.
+
+```ruby
+SlackMessage.post_as(:coffeebot) do
+  text ":coffee::clock: Time to take a break!"
+end
+```
+
+### Scheduling a Message
+
+To schedule a message, simply provide a `at` parameter to your post. Provide
+either a time object that responds to `to_i`, or an integer that represents a
+[unix timestamp](https://en.wikipedia.org/wiki/Unix_time) for the time at which
+you want your message posted.
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com', at: 20.seconds.from_now) do
+  text "From the top of the key. :basketball:"
+end
+
+SlackMessage.post_as(:basketball_bot, at: 20.seconds.from_now) do
+  text "Boom shakalaka! :explosion:"
+end
+```
+
+Please note that scheduled messages can't specify a `bot_name` or `bot_icon`,
+nor can they be scheduled more than 120 days into the future.
+
+### Best Practices
+
+Talk about having coherent methods that post a message, rather than a block
+that includes lots of indirection or ternaries.
+
+See the [API documentation for
+chat.postMessage](https://api.slack.com/methods/chat.postMessage) or
+[chat.scheduleMessage](https://api.slack.com/methods/chat.scheduleMessage) for
+more information on posting messages.
+
+---
+
+Next: [The SlackMessage DSL](https://jmmastey.github.io/slack_message/03_message_dsl)

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

@@ -59,7 +59,7 @@ module SlackMessage::Api
     if !time.nil?
       params[:post_at] = time.to_i
 
-      if params[:icon_url] || params[:icon_emoji]
+      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
@@ -72,6 +72,8 @@ module SlackMessage::Api
     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."
@@ -87,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
 
@@ -108,7 +155,7 @@ module SlackMessage::Api
   end
 
   def post_message(profile, params)
-    uri = if params[:post_at]
+    uri = if params.has_key?(:post_at)
       URI("https://slack.com/api/chat.scheduleMessage")
     else
       URI("https://slack.com/api/chat.postMessage")
@@ -124,4 +171,36 @@ module SlackMessage::Api
       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"
+      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/response.rb

@@ -0,0 +1,42 @@
+class SlackMessage::Response
+  attr_reader :channel, :timestamp, :profile_handle, :scheduled_message_id, :original_response
+
+  def initialize(api_response, profile_handle)
+    @original_response = JSON.parse(api_response.body)
+    @ok = @original_response["ok"]
+    @channel = @original_response["channel"]
+
+    @timestamp = @original_response["ts"]
+    @scheduled_message_id = @original_response["scheduled_message_id"]
+
+    @profile_handle = profile_handle
+  end
+
+  def marshal_dump
+    [ @profile_handle, @channel, @timestamp, @original_response, @ok, @original_response ]
+  end
+
+  def marshal_load(data)
+    @profile_handle, @channel, @timestamp, @original_response, @ok, @original_response = data
+  end
+
+  def sent_to_user?
+    channel =~ /^D.*/ # users are D for DM, channels start w/ C
+  end
+
+  def scheduled?
+    !!scheduled_message_id
+  end
+
+  def inspect
+    identifier = if scheduled?
+      "scheduled_message_id=#{scheduled_message_id}"
+    else
+      "timestamp=#{timestamp}"
+    end
+
+    ok_msg = @ok ? "ok" : "error"
+
+    "<SlackMessage::Response #{ok_msg} profile_handle=:#{profile_handle} channel=#{channel} #{identifier}>"
+  end
+end

data/lib/slack_message/rspec.rb

@@ -14,6 +14,8 @@ require 'rspec/mocks'
 # it can be cleaned up properly.
 #
 
+# TODO: testing for scheduled messages, editing and deleting
+
 module SlackMessage::RSpec
   extend RSpec::Matchers::DSL
 

data/lib/slack_message.rb

@@ -1,4 +1,5 @@
 module SlackMessage
+  require 'slack_message/response'
   require 'slack_message/dsl'
   require 'slack_message/api'
   require 'slack_message/configuration'
@@ -39,16 +40,46 @@ module SlackMessage
       raise ArgumentError, "Sorry, you need to specify a default_channel for profile #{profile_name} to use post_as"
     end
 
+    target  = profile[:default_channel]
     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 =~ EMAIL_PATTERN
 
     Api.post(payload, target, profile, at)
   end
 
+  def self.update(message, &block)
+    unless message.is_a?(SlackMessage::Response)
+      raise ArgumentError, "You must pass in a SlackMessage::Response to update a message"
+    end
+
+    if message.scheduled?
+      raise ArgumentError, "Sorry, scheduled messages cannot be updated. You will need to delete the message and schedule a new one."
+    end
+
+    profile = Configuration.profile(message.profile_handle)
+    payload = Dsl.new(block, profile).tap do |instance|
+      instance.instance_eval(&block)
+    end
+
+    Api.update(payload, message, profile)
+  end
+
+  def self.delete(message)
+    unless message.is_a?(SlackMessage::Response)
+      raise ArgumentError, "You must pass in a SlackMessage::Response to delete a message"
+    end
+
+    if message.sent_to_user?
+      raise ArgumentError, "It's not possible to delete messages sent directly to users."
+    end
+
+    profile = Configuration.profile(message.profile_handle)
+    Api.delete(message, profile)
+  end
+
   def self.build(profile_name = :default, &block)
     profile = Configuration.profile(profile_name)
 

data/slack_message.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name        = 'slack_message'
-  gem.version     = "2.4.0"
+  gem.version     = "3.0.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

@@ -157,4 +157,6 @@ RSpec.describe SlackMessage do
       }.to post_to_slack.with_content_matching(/ABC123/)
     end
   end
+
+  # tests for actual sending methods? what would actually be useful?
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_message
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-13 00:00:00.000000000 Z
+date: 2021-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -66,10 +66,19 @@ files:
 - Gemfile
 - MIT-LICENSE
 - README.md
+- docs/01_configuration.md
+- docs/02_posting_a_message.md
+- docs/03_message_dsl.md
+- docs/04_editing_messages.md
+- docs/05_deleting_messages.md
+- docs/06_notifying_users.md
+- docs/07_testing.md
+- docs/index.md
 - lib/slack_message.rb
 - lib/slack_message/api.rb
 - lib/slack_message/configuration.rb
 - lib/slack_message/dsl.rb
+- lib/slack_message/response.rb
 - lib/slack_message/rspec.rb
 - slack_message.gemspec
 - spec/slack_message_spec.rb