slack_message 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62f8b7feb3289a37b79cb887dc4e7846c037a8c72290138afe611682a066a884
-  data.tar.gz: 73e391d721ace67ad31ae69b7a17eae3578d4f85a2bcd111a5cb1966b68c85cd
+  metadata.gz: 2b4cc88c84b2a958d75262b0d1fea97de8b7b694555159e4962a4a9fa16c55f6
+  data.tar.gz: 750afd5d7321952cc9dbf344d6db3659f85d916f988ca7ac3e56ec615cde4b34
 SHA512:
-  metadata.gz: cb28febfda107047351955825d1cd84dafdf553147b9f0101573944f3d5290c6d3e84a4d1190e63888f6c8ba851ac70da9eb774f1a01a04372d19520b7df8779
-  data.tar.gz: 3438883916204aec8a16a8dfa80b52506d4f640fc69161ad6e8efea1b5a136e97fc15f8b990c2529f3bbfb1f4380a989a0827cbe8f810af08a42bf3a2b6df382
+  metadata.gz: 7eb4393b8e51b899a65abe790f4e217522441274bc6cc418ea21e43257716d218ad87fbddfce2fd7521f4305840312967249f4faf20261f5f7b665ec01d55896
+  data.tar.gz: ce790defaa92aeea75683771a85ef827386a1275524ac6006139aa3db58e387797ae5f8b8623e6896f07c5af0e6fd881b2878bac1cadf1be398333ab20066a2c

data/.github/workflows/main.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby-version: [3.0, 2.7, 2.6, 2.5]
+        ruby-version: ['3.1', '3.0', '2.7', '2.6', '2.5']
     runs-on: ${{ matrix.os }}
 
     steps:

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.1.0] - TBD
+- Methods from the calling context can now be called within a section block.
+
+## [3.0.2] - 2022-04-16
+- Fix tests on ruby 3.0.
+- More adjustments and additions to docs.
+- Add warnings when overriding notification text and context block.
+
+## [3.0.1] - 2021-12-22
+- Major overhaul of error handling and expansion on which errors trigger
+  friendly messages for users.
+- More additions to the docs, and working github pages integration.
+- It's my birthday!
+
 ## [3.0.0] - 2021-12-19
 - Return a more structured object from successful message sends.
 - Add the ability to edit or delete a message.

data/README.md

@@ -12,13 +12,18 @@ SlackMessage.post_to('#general') do
   text "We did it @here! :thumbsup:"
 end
 ```
+ 
+### The Docs
 
-#### Posting
+You'll find much more information about how to use SlackMessage by visiting
+[the docs](https://jmmastey.github.io/slack_message).
+ 
 
-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, you should play around with Slack's [Block Kit
-Builder](https://app.slack.com/block-kit-builder/). There are lots of options:
+### A Rich DSL Focused on Maintainability
+
+SlackMessage is able to build all kinds of rich messages for you. It focuses on
+writing code that looks similar to the output messages themselves, with as
+little repetition and cruft as possible.
 
 ```ruby
 SlackMessage.post_to('#general') do
@@ -48,12 +53,7 @@ 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
+### Opinionated Stances
 
 This gem is intended to stay simple. Other Slack gems have lots of config
 options and abilities, which makes them powerful, but makes them a pain to use.
@@ -61,6 +61,8 @@ options and abilities, which makes them powerful, but makes them a pain to use.
 Accordingly, SlackMessage is developed with some strong opinions in mind:
 
 * SlackMessage has no dependencies. Your lockfile is enough of a mess already.
+* A DSL that focuses on code that is easy to write, read, and maintain. Only
+  features that can be implemented with that in mind are included.
 * The code to build a message should look a lot like the message itself. Code
   that is simple to read and understand is a priority.
 * Webhooks are passé. Only Slack Apps are supported now.
@@ -71,28 +73,28 @@ Accordingly, SlackMessage is developed with some strong opinions in mind:
   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.
+* Configuration is kept simple, with helpers for frequently reused bots.
 
-Some behaviors that are still planned but not yet added:
+Some changes that are still planned or desired, but not yet added:
 
 * any interactive elements at all: https://api.slack.com/interactivity/handling
 * 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
+* more mrkdwn syntax, like quotes or code blocks https://api.slack.com/reference/surfaces/formatting#line-breaks
+* more and better organized testing capability (for scheduled messages, editing, deleting)
 * 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)
+* easier way to dump / load message responses
+* updated docs w/ links to BlockBuilder
 
-Contributing
-------------
+### Contributing
 
-Contributions are very welcome. Fork, fix, submit pull. Since simplicity of API is a strong priority, so opening an issue to discuss possible interface changes would be wise.
+Contributions are very welcome. Fork, fix, submit pull. Since simplicity of API
+is a strong priority, so opening an issue to discuss possible interface changes
+would be wise.
 
-Contribution is expected to conform to the [Contributor Covenant](https://github.com/jmmastey/slack_message/blob/master/CODE_OF_CONDUCT.md).
+Contribution is expected to conform to the [Contributor
+Covenant](https://github.com/jmmastey/slack_message/blob/master/CODE_OF_CONDUCT.md).
 
-License
-------------
+### License
 
-This software is released under the [MIT License](https://github.com/jmmastey/slack_message/blob/master/MIT-LICENSE).
+This software is released under the [MIT
+License](https://github.com/jmmastey/slack_message/blob/master/MIT-LICENSE).

data/docs/01_configuration.md

@@ -95,18 +95,18 @@ 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,
-  }
+{
+  :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`.

data/docs/02_posting_a_message.md

@@ -101,7 +101,7 @@ end
 
 ### Scheduling a Message
 
-To schedule a message, simply provide a `at` parameter to your post. Provide
+To schedule a message, simply provide an `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.
@@ -121,8 +121,12 @@ 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.
+From experience, building messages with maintainability in mind is key. Adding
+lots of flow control and indirection will undermine your ability to understand
+and change messages later.
+
+For simple messages, using implicit sections is perfectly fine. However, if you
+intend to create several sections, it's usually better to just declare them.
 
 See the [API documentation for
 chat.postMessage](https://api.slack.com/methods/chat.postMessage) or

data/docs/03_message_dsl.md

@@ -1,10 +1,15 @@
-### The Message DSL
+## 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.
+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
+### 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.
+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
@@ -108,7 +113,51 @@ end
 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
+### Explicitly Declared 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 an `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. But, you may have troubles when you start adding
+more complicated elements to your messages.
+
+### 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
@@ -132,10 +181,10 @@ end
 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.
+confusing when there is a style specifically named default, 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.
+You can override button style by specifying the style with your link button.
 
 ```ruby
 SlackMessage.build do
@@ -152,62 +201,114 @@ end
 #   :style=>:danger}}]
 ```
 
-#### Lists and List Items
+### Ordered and Unordered Lists
 
-- list_item, ul, ol
+The Slack API doesn't have native support for HTML-style ordered and unordered
+lists, but there are convenience methods in SlackMessage to render a close
+approximation.
 
-### Including Multiple Sections
+```ruby
+SlackMessage.build do
+  section do
+    text '*Pet Goodness Tiers*'
+
+    ol([
+      'tiny pigs',
+      'reptiles',
+      'dogs',
+      'cats',
+    ])
+  end
 
-Adding more sections is trivial. Simply declare each section and it will be
-separated in the rendered message. This can often occur when looping.
+  section do
+    text '_voted by_'
+    ul(['Joe', 'Emily', 'Sophia', 'Matt'])
+  end
+end
+```
+
+Because Slack automatically collapses leading whitespace, indention of lists is
+handled using unicode emspaces. Bullets for unordered lists are also unicode
+characters to avoid being read as markdown.
+
+### List Items (e.g. HTML dt & dd)
+
+When trying to represent title / value lists, you can use the "list item" block
+type to pass a set of values. Slack does not allow you to customize how many
+items are shown per line, so you'll just have to work with it.
 
 ```ruby
 SlackMessage.build do
-  pet_types.each do |type, breeds|
-    section do
-      text "*#{type}:* #{breeds.join(", ")}"
-    end
-  end
+  text 'Import results are available!'
+
+  list_item 'Import Date', Date.today.to_s
+  list_item 'Items Imported', 55_000
+  list_item 'Errors', 23
+  list_item 'Bad Values', errors.map(&:to_s)
 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.
+### Images and Accessory Images
+
+There are two main types of images in Slack: the
+[image](https://imgur.com/XEUap1r) and the [accessory
+image](https://imgur.com/zuhjBDq). In short, `accessory_image` is part of a
+section itself and is shown alongside an existing block, while `image` is shown
+as its own top-level element.
+
+Accordingly, an accessory image should be used within a section. An accessory
+image can accept alt-text, which is also a best practice, for usability
+reasons.
 
 ```ruby
 SlackMessage.build do
   section do
-    text "*Topsiders:* Emily, Elsie, Derick"
+    text 'Looks like the coffee machine is empty.'
+    accessory_image 'https://your.com/empty_coffee_logo.jpg', alt_text: 'logo of a forlorn coffee cup'
   end
+end
+```
 
-  divider
+Only one accessory image can be used per section, and declaring more will issue
+a warning and simply override the previous accessory image.
 
+By contrast, `image` can be used many times, and will create a new top-level
+section for each call. Image accepts alt-text, but also a title, which will
+be displayed above the image (along with an icon to collapse the image).
+
+```ruby
+SlackMessage.build do
   section do
-    text "*Undergrounders:* Kristina, Lauren, Different Emily"
+    text 'Most Recent Tiny Pig Images'
   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"}}
-# ]
+  image 'https://your.com/employee_pets/best/pig_1.jpg', alt_text: 'a tiny pig eating ice cream', title: 'Spider Pig'
+  image 'https://your.com/employee_pets/best/pig_2.jpg', alt_text: 'a tiny pig smiling mischeviously', title: 'Porkeypine'
+  image 'https://your.com/employee_pets/best/pig_3.jpg', alt_text: 'a tiny pig with wellies and an umbrella', title: 'Albert Sweinstein'
+end
 ```
 
-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.
+Sectionless messages can also use `accessory_image`, but this can get confusing
+since they could potentially be interspersed with top-level images, so I
+wouldn't recommend it.
 
-### Images
-- image, accessory_image
+```ruby
+# the difference between these two image styles is confusing, and the call
+# to `image` closed the current section and started a new one.
+SlackMessage.build do
+  text 'Looks like the coffee machine is empty.'
+  accessory_image 'https://your.com/empty_coffee_logo.jpg'
+
+  text '*Most Recent Coffee Maker Surveillance Photo*'
+  image 'https://your.com/surveillance/coffee/current.jpg'
+end
+```
 
 ### 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.
+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
@@ -225,15 +326,16 @@ end
 # }]
 ```
 
-Context does not belong to a section, and is per-message, not per-section.
-Specifying more than one context will simply overwrite previous calls.
+Context does not belong to a section, and only one can be added to your entire
+slack message. Specifying another `context` will issue a warning and overwrite
+any previous call.
 
 ### 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.
+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
@@ -247,9 +349,9 @@ end
 ```
 
 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.
+To view the change to the message payload from these calls, use `debug` mode.
 
-The `bot_icon` can be specified as either an emoji (`:example:`), or a URL
+The `bot_icon` can be specified as either an emoji (`:shipit:`), or a URL
 pointing to an image (`http://mysite.com/shipit.png`). Any other value seems to
 cause an error.
 
@@ -276,7 +378,9 @@ 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.
+you will need to enable debugging to see how it changes what is sent to the
+API.  Only one custom notification is allowed, so further calls will issue a
+warning and replace the previous notification text.
 
 ---
 

data/docs/04_editing_messages.md

@@ -1,4 +1,4 @@
-### Updating a Previous Message
+## 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.
@@ -52,12 +52,11 @@ class SomeWorker < ApplicationWorker
 end
 ```
 
-#### Storing Response Objects for Later
+### 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.
+Since updates are likely to occur long after you post the original message, you
+may want to persist a reference to the message until you need to update it
+later. As one option, you could serialize the response object for later.
 
 ```ruby
 # initially
@@ -74,7 +73,7 @@ SlackMessage.update(message) do
 end
 ```
 
-#### Updating Scheduled Messages
+### 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.

data/docs/05_deleting_messages.md

@@ -1,26 +1,26 @@
-### Deleting Messages
+## 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.
+Then you can simply call the `delete` method to make up for your mistakes.
 
 ```ruby
 SlackMessage.delete(message)
 ```
 
+*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.*
+
 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.
+database to be removed at a later date.
 
 ```ruby
 # initially

data/docs/06_notifying_users.md

@@ -47,7 +47,7 @@ SlackMessage.post_to('hello@joemastey.com') do
 end
 ```
 
-#### Using @channel or @here
+### Using @channel or @here
 
 Not really a feature, but Slack will respect usage of `@here` and `@channel`.
 

data/docs/_config.yml

@@ -0,0 +1,6 @@
+plugins:
+  - jekyll-relative-links
+relative_links:
+  enabled: true
+  collections: true
+theme: jekyll-theme-midnight

data/docs/index.md

@@ -1,7 +1,53 @@
-* [Configuration](https://jmmastey.github.io/slack_message/01_configuration)
+* [Getting Started / 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)
+
+SlackMessage is a gem that makes it easy to send messages to Slack from your
+application. _Really_ easy.
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "We did it @here! :thumbsup:"
+end
+```
+
+And not just simple messages. You can compose complicated messages quickly in a
+DSL that's focused on usability and maintainability. It can be tough to
+maintain code in other similar gems, but not here.
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  section do
+    text "A job has generated some output for you to review."
+    text 'And More' * 10
+    link_button "See Results", "https://google.com"
+  end
+
+  section do
+    text ":unlock-new: New Data Summary"
+
+    list_item "Date", "09/05/2021"
+    list_item "Total Imported", 45_004
+    list_item "Total Errors", 5
+  end
+
+  divider
+
+  section do
+    text "See more here: #{link('result', 'https://google.com')}"
+  end
+
+  context "Kicked off by <hello@joemastey.com> at **9:05am**"
+end
+```
+
+It has no dependencies and minimal configuration needs, so you can get up and
+running quickly.
+
+---
+
+Next: [Get Started](https://jmmastey.github.io/slack_message/01_configuration)

data/lib/slack_message/api.rb

@@ -10,6 +10,10 @@ module SlackMessage::Api
       raise ArgumentError, "Tried to find profile by invalid email address '#{email}'"
     end
 
+    if SlackMessage::Configuration.debugging?
+      warn [email, profile].inspect
+    end
+
     response = look_up_user_by_email(email, profile)
 
     if response.code != "200"
@@ -24,14 +28,7 @@ module SlackMessage::Api
       raise SlackMessage::ApiError, "Unable to parse JSON response from Slack API\n#{response.body}"
     end
 
-    if payload.include?("error") && payload["error"] == "invalid_auth"
-      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 SlackMessage::ApiError, "Received error response from Slack during user lookup:\n#{response.body}"
-    end
-
+    SlackMessage::ErrorHandling.raise_user_lookup_errors(response, target, profile)
     payload["user"]["id"]
   end
 
@@ -69,26 +66,8 @@ module SlackMessage::Api
     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."
-    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 SlackMessage::ApiError, "Got 302 response while posting to Slack. Check your API key for profile '#{profile[:handle]}'."
-    elsif response.code != "200"
-      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
-    end
 
+    SlackMessage::ErrorHandling.raise_post_response_errors(response, params, profile)
     SlackMessage::Response.new(response, profile[:handle])
   end
 
@@ -97,7 +76,7 @@ module SlackMessage::Api
       channel: message.channel,
       ts: message.timestamp,
       blocks: payload.render,
-      text: payload.custom_notification # TODO: ???
+      text: payload.custom_notification
     }
 
     if params[:blocks].length == 0
@@ -112,8 +91,7 @@ module SlackMessage::Api
     body  = JSON.parse(response.body)
     error = body.fetch("error", "")
 
-    # TODO: error messaging
-
+    SlackMessage::ErrorHandling.raise_post_response_errors(response, message, profile)
     SlackMessage::Response.new(response, profile[:handle])
   end
 
@@ -130,10 +108,13 @@ module SlackMessage::Api
       }
     end
 
-    response = delete_message(profile, params)
+    if SlackMessage::Configuration.debugging?
+      warn params.inspect
+    end
 
-    # TODO error handling (incl for already scheduled-and-sent messages)
+    response = delete_message(profile, params)
 
+    SlackMessage::ErrorHandling.raise_delete_response_errors(response, message, profile)
     response
   end
 

data/lib/slack_message/dsl.rb

@@ -63,6 +63,13 @@ class SlackMessage::Dsl
 
     text = self.enrich_text(text)
 
+
+    previous_context = @body.find { |element| element[:type] && element[:type] == "context" }
+    if previous_context
+      previous_text = previous_context[:elements].first[:text]
+      warn "WARNING: Overriding previous context in section: #{previous_text}"
+    end
+
     @body.push({ type: "context", elements: [{
       type: "mrkdwn", text: text
     }]})
@@ -94,6 +101,10 @@ class SlackMessage::Dsl
   end
 
   def notification_text(msg)
+    if @custom_notification
+      warn "WARNING: Overriding previous custom notification text: #{@custom_notification}"
+    end
+
     @custom_notification = msg
   end
 
@@ -261,6 +272,10 @@ class SlackMessage::Dsl
 
       body
     end
+
+    def method_missing(meth, *args, &blk)
+      @parent.send meth, *args, &blk
+    end
   end
 
   class List

data/lib/slack_message/error_handling.rb

@@ -0,0 +1,124 @@
+class SlackMessage::ErrorHandling
+  PERMISSIONS_ERRORS = ["token_revoked", "token_expired", "invalid_auth", "not_authed",
+                        "team_access_not_granted", "no_permission", "missing_scope",
+                        "not_allowed_token_type", "ekm_access_denied"]
+
+  def self.raise_post_response_errors(response, params, profile)
+    body  = JSON.parse(response.body)
+    error = body.fetch("error", "")
+
+    if ["invalid_blocks", "invalid_blocks_format"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't send Slack message because the serialized message had an invalid format"
+    elsif error == "channel_not_found"
+      raise SlackMessage::ApiError, "Tried to send Slack message to non-existent channel or user '#{params[:channel]}'"
+
+    # scheduling messages
+    elsif error == "invalid_time"
+      raise SlackMessage::ApiError, "Couldn't schedule Slack message because you requested an invalid time '#{params[:post_at]}'"
+    elsif error == "time_in_past"
+      raise SlackMessage::ApiError, "Couldn't schedule Slack message because you requested a time in the past (or too close to now) '#{params[:post_at]}'"
+    elsif error == "time_too_far"
+      raise SlackMessage::ApiError, "Couldn't schedule Slack message because you requested a time more than 120 days in the future '#{params[:post_at]}'"
+
+
+    elsif PERMISSIONS_ERRORS.include?(error)
+      raise SlackMessage::ApiError, "Couldn't send Slack message because the API key for profile '#{profile[:handle]}' is wrong, or the app has insufficient permissions (#{error})"
+    elsif error == "message_too_long"
+      raise SlackMessage::ApiError, "Tried to send Slack message, but the message was too long"
+    elsif error == "invalid_arguments"
+      raise SlackMessage::ApiError, "Tried to send Slack message with invalid payload"
+    elsif ["rate_limited", "ratelimited"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't send Slack message because you've reached your rate limit"
+    elsif response.code == "302"
+      raise SlackMessage::ApiError, "Got 302 response while posting to Slack. Check your API key for profile '#{profile[:handle]}'"
+    elsif response.code != "200"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+    elsif !(error.nil? || error == "")
+      raise SlackMessage::ApiError, "Received error response from Slack during message posting:\n#{response.body}"
+    end
+  end
+
+  def self.raise_update_response_errors(response, message, profile)
+    body  = JSON.parse(response.body)
+    error = body.fetch("error", "")
+
+    if ["invalid_blocks", "invalid_blocks_format"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't update Slack message because the serialized message had an invalid format"
+    elsif error == "channel_not_found"
+      raise SlackMessage::ApiError, "Tried to update Slack message to non-existent channel or user '#{message.channel}'"
+
+    elsif error == "message_not_found"
+      raise SlackMessage::ApiError, "Tried to update Slack message, but the message wasn't found (timestamp '#{message.timestamp}' for channel '#{message.channel}'"
+    elsif error == "cant_update_message"
+      raise SlackMessage::ApiError, "Couldn't update message because the message type isn't able to be updated, or #{profile[:handle]} isn't allowed to update it"
+    elsif error == "edit_window_closed"
+      raise SlackMessage::ApiError, "Couldn't update message because it's too old"
+
+
+    elsif PERMISSIONS_ERRORS.include?(error)
+      raise SlackMessage::ApiError, "Couldn't update Slack message because the API key for profile '#{profile[:handle]}' is wrong, or the app has insufficient permissions (#{error})"
+    elsif error == "message_too_long"
+      raise SlackMessage::ApiError, "Tried to update Slack message, but the message was too long"
+    elsif error == "invalid_arguments"
+      raise SlackMessage::ApiError, "Tried to update Slack message with invalid payload"
+    elsif ["rate_limited", "ratelimited"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't update Slack message because you've reached your rate limit"
+    elsif response.code == "302"
+      raise SlackMessage::ApiError, "Got 302 response while updating a message. Check your API key for profile '#{profile[:handle]}'"
+    elsif response.code != "200"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+    elsif !(error.nil? || error == "")
+      raise SlackMessage::ApiError, "Received error response from Slack during message update:\n#{response.body}"
+    end
+  end
+
+  def self.raise_delete_response_errors(response, message, profile)
+    body  = JSON.parse(response.body)
+    error = body.fetch("error", "")
+
+    if error == "channel_not_found"
+      raise SlackMessage::ApiError, "Tried to delete Slack message in non-existent channel '#{message.channel}'"
+
+    elsif error == "invalid_scheduled_message_id"
+      raise SlackMessage::ApiError, "Can't delete message because the ID was invalid, or the message has already posted (#{message.scheduled_message_id})"
+    elsif error == "message_not_found"
+      raise SlackMessage::ApiError, "Tried to delete Slack message, but the message wasn't found (timestamp '#{message.timestamp}' for channel '#{message.channel}')"
+    elsif error == "cant_delete_message"
+      raise SlackMessage::ApiError, "Can't delete message because '#{profile[:handle]}' doesn't have permission to"
+    elsif error == "compliance_exports_prevent_deletion"
+      raise SlackMessage::ApiError, "Can't delete message because team compliance settings prevent it"
+
+
+    elsif PERMISSIONS_ERRORS.include?(error)
+      raise SlackMessage::ApiError, "Couldn't delete Slack message because the API key for profile '#{profile[:handle]}' is wrong, or the app has insufficient permissions (#{error})"
+    elsif ["rate_limited", "ratelimited"].include?(error)
+      raise SlackMessage::ApiError, "Couldn't delete Slack message because you've reached your rate limit"
+    elsif response.code == "302"
+      raise SlackMessage::ApiError, "Got 302 response while deleting a message. Check your API key for profile '#{profile[:handle]}'"
+    elsif response.code != "200"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+    elsif !(error.nil? || error == "")
+      raise SlackMessage::ApiError, "Received error response from Slack during message delete:\n#{response.body}"
+    end
+  end
+
+  def self.raise_user_lookup_response_errors(payload)
+    error = payload["error"]
+
+    if error == "users_not_found"
+      raise SlackMessage::ApiError, "Couldn't find a user with the email '#{email}'"
+
+
+    elsif PERMISSIONS_ERRORS.include?(error)
+      raise SlackMessage::ApiError, "Couldn't look up users because the API key for profile '#{profile[:handle]}' is wrong, or the app has insufficient permissions (#{error})"
+    elsif error
+      raise SlackMessage::ApiError, "Received error response from Slack during user lookup:\n#{response.body}"
+    elsif response.code == "302"
+      raise SlackMessage::ApiError, "Got 302 response during user lookup. Check your API key for profile '#{profile[:handle]}'"
+    elsif response.code != "200"
+      raise SlackMessage::ApiError, "Got an error back from the Slack API (HTTP #{response.code}):\n#{response.body}"
+    elsif !(error.nil? || error == "")
+      raise SlackMessage::ApiError, "Received error response from Slack during user lookup:\n#{response.body}"
+    end
+  end
+end

data/lib/slack_message/rspec.rb

@@ -14,12 +14,15 @@ require 'rspec/mocks'
 # it can be cleaned up properly.
 #
 
-# TODO: testing for scheduled messages, editing and deleting
+# TODO: test helpers for scheduled messages, editing and deleting, and
+# notification text. And realistically, overhaul all this.
 
 module SlackMessage::RSpec
   extend RSpec::Matchers::DSL
 
   @@listeners = []
+  @@custom_response = {}
+  @@response_code = '200'
 
   def self.register_expectation_listener(expectation_instance)
     @@listeners << expectation_instance
@@ -29,6 +32,11 @@ module SlackMessage::RSpec
     @@listeners.delete(expectation_instance)
   end
 
+  def self.reset_custom_responses
+    @@custom_response = {}
+    @@response_code = '200'
+  end
+
   FauxResponse = Struct.new(:code, :body)
 
   def self.included(_)
@@ -38,22 +46,24 @@ module SlackMessage::RSpec
         listener.record_call(params.merge(profile: profile))
       end
 
-      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)
+      response = {
+       "ok" => true,
+       "channel" => "C12345678",
+       "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}}
+                     ]
+       }
+      }.merge(@@custom_response).to_json
+
+      return FauxResponse.new(@@response_code, response)
     end
 
     SlackMessage::Api.undef_method(:look_up_user_by_email)
@@ -63,6 +73,18 @@ module SlackMessage::RSpec
     end
   end
 
+  def self.respond_with(response = {}, code: '200')
+    raise ArgumentError, "custom response must be a hash" unless response.is_a? Hash
+
+    @@custom_response = response
+    @@response_code = code
+  end
+
+  def self.reset_mock_response
+    @@custom_response = {}
+    @@response_code = '200'
+  end
+
   # w/ channel
   matcher :post_slack_message_to do |expected|
     match do |actual|

data/lib/slack_message.rb

@@ -1,6 +1,7 @@
 module SlackMessage
   require 'slack_message/response'
   require 'slack_message/dsl'
+  require 'slack_message/error_handling'
   require 'slack_message/api'
   require 'slack_message/configuration'
 

data/slack_message.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name        = 'slack_message'
-  gem.version     = "3.0.0"
+  gem.version     = "3.1.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,8 +1,13 @@
 require 'spec_helper'
 
 RSpec.describe SlackMessage do
+
   describe "DSL" do
     describe "#build" do
+      def outer_method
+       "foo"
+      end
+
       it "renders some JSON" do
         SlackMessage.configure do |config|
           config.clear_profiles!
@@ -12,11 +17,17 @@ RSpec.describe SlackMessage do
         expected_output = [
           { type: "section",
             text: { text: "foo", type: "mrkdwn" }
-          }
+          },
+          { type: "section",
+            text: { text: "foo", type: "mrkdwn" }
+          },
         ]
 
         output = SlackMessage.build do
-          text "foo"
+          text outer_method()
+          section do
+            text outer_method()
+          end
         end
 
         expect(output).to eq(expected_output)
@@ -49,6 +60,13 @@ RSpec.describe SlackMessage do
       end
     end
 
+    fit do
+      SlackMessage.build do
+        notification_text 'one'
+        notification_text 'two'
+      end
+    end
+
     it "can assert expectations against posts" do
       expect {
         SlackMessage.post_to('#lieutenant') { text "foo" }
@@ -111,10 +129,6 @@ RSpec.describe SlackMessage do
       }.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" }
@@ -123,8 +137,6 @@ RSpec.describe SlackMessage do
   end
 
   describe "API convenience" do
-    let(:profile) { SlackMessage::Configuration.profile(:default) }
-
     before do
       SlackMessage.configure do |config|
         config.clear_profiles!
@@ -158,5 +170,57 @@ RSpec.describe SlackMessage do
     end
   end
 
-  # tests for actual sending methods? what would actually be useful?
+  describe "error handling" do
+    before do
+      SlackMessage.configure do |config|
+        config.clear_profiles!
+        config.add_profile(name: 'default profile', api_token: 'abc123')
+        config.add_profile(:schmoebot, name: 'Schmoe', api_token: 'abc123', icon: ':schmoebot:', default_channel: '#schmoes')
+      end
+    end
+
+    after do
+      SlackMessage::RSpec.reset_mock_response
+    end
+
+    it "raises nice error messages when API methods return errors" do
+      SlackMessage::RSpec.respond_with({'error' => 'nuffin'})
+
+      expect {
+        SlackMessage.post_to('#general') { text 'nuh uh' }
+      }.to raise_error(SlackMessage::ApiError)
+
+      expect {
+        SlackMessage.post_as(:schmoebot) { text 'nuh uh' }
+      }.to raise_error(SlackMessage::ApiError)
+    end
+
+    it "raises for redirects" do
+      SlackMessage::RSpec.respond_with(code: '302')
+
+      expect {
+        SlackMessage.post_to('#general') { text 'nuh uh' }
+      }.to raise_error(SlackMessage::ApiError)
+    end
+
+    it "raises errors w/ updates too" do
+      message = SlackMessage.post_to('#general') { text 'nuh uh' }
+
+      SlackMessage::RSpec.respond_with({'error' => 'bad choice'})
+
+      expect {
+        SlackMessage.update(message) { text 'nuh uh' }
+      }.to raise_error(SlackMessage::ApiError)
+    end
+
+    it "even raises errors during deletes" do
+      message = SlackMessage.post_to('#general') { text 'nuh uh' }
+
+      SlackMessage::RSpec.respond_with({'error' => 'bad choice'})
+
+      expect {
+        SlackMessage.delete(message) { text 'nuh uh' }
+      }.to raise_error(SlackMessage::ApiError)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_message
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-20 00:00:00.000000000 Z
+date: 2022-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -73,11 +73,13 @@ files:
 - docs/05_deleting_messages.md
 - docs/06_notifying_users.md
 - docs/07_testing.md
+- docs/_config.yml
 - 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/error_handling.rb
 - lib/slack_message/response.rb
 - lib/slack_message/rspec.rb
 - slack_message.gemspec