slack_message 2.4.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b97efc9f2b80be4ee01c89d4c82aab83bb79983077ec8bfa87f0026ea5387f37
-  data.tar.gz: ae251f82220f9c15e45d3065f4e8cd84f5ad913c630a48d6cf9713df33b41b34
+  metadata.gz: 100c64a0e3204d4715ffde4c0a11e0b380c7966289b8b841ef2ab7cb73f657b2
+  data.tar.gz: 3213f9c1817a211f57685002025dc72929f41652ba7c9e69e62d5314508fc3dd
 SHA512:
-  metadata.gz: c2e5a3f499fe2e73f245ff2163284f73825f3d051c4cc06aee03c39184eb01e22d6ce5d426f1dde77a0f89e6eacd1764b3a49b1f0548a368490588a7dc0bd757
-  data.tar.gz: d2417ed29a6b0e3b88133e9e679a965104d2b9030945d7241af106b54dabc471190d73902f4a4bceae02a469f24eeeeb6e95d91f1b8c9817dc0f69ee41a6524d
+  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,21 @@
 # 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.
+- 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.
+- 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

@@ -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,7 +53,7 @@ SlackMessage.post_to('#general') do
 end
 ```
 
-#### 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.
@@ -56,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.
@@ -66,26 +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 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
+* 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

@@ -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,138 @@
+## 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 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.
+
+```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
+
+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
+[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)