slack_message 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '098b332b278741ef63ef105fc7e79cbc7ef131a03dca79b0ed40a1d86001cae1'
-  data.tar.gz: 40a4028d38c154fdb1d1835e0f536adc2e57671223290e43a139be1d70a359c3
+  metadata.gz: 100c64a0e3204d4715ffde4c0a11e0b380c7966289b8b841ef2ab7cb73f657b2
+  data.tar.gz: 3213f9c1817a211f57685002025dc72929f41652ba7c9e69e62d5314508fc3dd
 SHA512:
-  metadata.gz: f99700c2fcb33cc7ad9e671f250dc23efffd47e6f4e36d9fdc7740c9ed1a8d4b224b523b6870b13cb3b164a0ae720f93824fae803368083919d776ec2c221236
-  data.tar.gz: 1fb9ccc9bf2f9b9fabca5e1cdcdbcde87100f1c056613f0af1450f344bc82adcc5f7366d2f6ab8fb54e34f241018464283c750f2a0d022a67112b9570fc1287e
+  metadata.gz: 238cdf0160b6c2101cbabdadef3818dd0bcd2163d9a3ababba854affa0fbaca2533489aa203b27a2309af8e85aa7e814786a9ce8eb29dd51d949cefc1d209921
+  data.tar.gz: b0ad7654cfcac475f32eb81ede6e730046ef3721190ae1f255ceaff58331fbf6d4ee570a290dc16e660ca32611cc8639998677c5980f2eaaedd72388293b22df

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,10 @@
 # Changelog
 
+## [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.

data/README.md

@@ -19,12 +19,11 @@ You'll find much more information about how to use SlackMessage by visiting
 [the docs](https://jmmastey.github.io/slack_message).
  
 
-### Posting
+### A Rich DSL Focused on Maintainability
 
-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:
+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
@@ -76,20 +75,26 @@ Accordingly, SlackMessage is developed with some strong opinions in mind:
   doesn't exist in the API), or leading spaces.
 * 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 mrkdwn syntax, like quotes or code blocks
-* more and better organized testing capability (scheduled messages, editing, deleting)
+* 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
+* easier way to dump / load message responses
+* updated docs w/ links to BlockBuilder
 
 ### 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
 
-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/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,7 +201,7 @@ end
 #   :style=>:danger}}]
 ```
 
-#### Ordered and Unordered Lists
+### Ordered and Unordered Lists
 
 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
@@ -182,7 +231,7 @@ 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)
+### 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
@@ -199,58 +248,67 @@ SlackMessage.build do
 end
 ```
 
-#### Including Multiple Sections
+### Images and Accessory Images
 
-Adding more sections is trivial. Simply declare each section and it will be
-separated in the rendered message. This can often occur when looping.
+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
-  pet_types.each do |type, breeds|
-    section do
-      text "*#{type}:* #{breeds.join(", ")}"
-    end
+  section do
+    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
 ```
 
-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.
+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 "*Topsiders:* Emily, Elsie, Derick"
+    text 'Most Recent Tiny Pig Images'
   end
 
-  divider
-
-  section do
-    text "*Undergrounders:* Kristina, Lauren, Different Emily"
-  end
+  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
-
-# => [
-#  {: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.
+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.
+
+```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'
 
-#### Images
-TODO: image, accessory_image
+  text '*Most Recent Coffee Maker Surveillance Photo*'
+  image 'https://your.com/surveillance/coffee/current.jpg'
+end
+```
 
-#### Footers (Context)
+### 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
@@ -268,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
+### 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
@@ -290,13 +349,13 @@ 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.
 
-#### Custom Notification Text
+### 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
@@ -319,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/index.md

@@ -47,3 +47,7 @@ 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/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
 

data/slack_message.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name        = 'slack_message'
-  gem.version     = "3.0.1"
+  gem.version     = "3.0.2"
   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,6 +1,7 @@
 require 'spec_helper'
 
 RSpec.describe SlackMessage do
+
   describe "DSL" do
     describe "#build" do
       it "renders some JSON" do
@@ -49,6 +50,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" }
@@ -166,7 +174,7 @@ RSpec.describe SlackMessage do
     end
 
     it "raises nice error messages when API methods return errors" do
-      SlackMessage::RSpec.respond_with('error' => 'nuffin')
+      SlackMessage::RSpec.respond_with({'error' => 'nuffin'})
 
       expect {
         SlackMessage.post_to('#general') { text 'nuh uh' }
@@ -188,7 +196,7 @@ RSpec.describe SlackMessage do
     it "raises errors w/ updates too" do
       message = SlackMessage.post_to('#general') { text 'nuh uh' }
 
-      SlackMessage::RSpec.respond_with('error' => 'bad choice')
+      SlackMessage::RSpec.respond_with({'error' => 'bad choice'})
 
       expect {
         SlackMessage.update(message) { text 'nuh uh' }
@@ -198,7 +206,7 @@ RSpec.describe SlackMessage do
     it "even raises errors during deletes" do
       message = SlackMessage.post_to('#general') { text 'nuh uh' }
 
-      SlackMessage::RSpec.respond_with('error' => 'bad choice')
+      SlackMessage::RSpec.respond_with({'error' => 'bad choice'})
 
       expect {
         SlackMessage.delete(message) { text 'nuh uh' }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_message
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.0.2
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-23 00:00:00.000000000 Z
+date: 2022-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec