slack_message 2.3.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b476b987543e7a38fd316de55186ddee859dfc1bd71817b14ddd13b2cb79f59
-  data.tar.gz: 80932a2d8e1bcac51239ea7724cd42f419dadfb7061fd939f359c2f4a5743777
+  metadata.gz: '098b332b278741ef63ef105fc7e79cbc7ef131a03dca79b0ed40a1d86001cae1'
+  data.tar.gz: 40a4028d38c154fdb1d1835e0f536adc2e57671223290e43a139be1d70a359c3
 SHA512:
-  metadata.gz: c6273ff440e4aa2fd9c4dba40c7e45e4c3840d02d7619dafb11d516f9a3541172499e0e81f1966103a89332bb3911fb96818984fadc0195faa27c9b5e1692fcb
-  data.tar.gz: fc1a7df622d0cfd0c10311a70478cba43b893d7cde189d4f55dd997196e544145f8ce855a4b82af920f4320314907a6fe91bb39fddf3ba5e9460d4b8a4cbb33a
+  metadata.gz: f99700c2fcb33cc7ad9e671f250dc23efffd47e6f4e36d9fdc7740c9ed1a8d4b224b523b6870b13cb3b164a0ae720f93824fae803368083919d776ec2c221236
+  data.tar.gz: 1fb9ccc9bf2f9b9fabca5e1cdcdbcde87100f1c056613f0af1450f344bc82adcc5f7366d2f6ab8fb54e34f241018464283c750f2a0d022a67112b9570fc1287e

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]
+        ruby-version: [3.0, 2.7, 2.6, 2.5]
     runs-on: ${{ matrix.os }}
 
     steps:

data/.gitignore

@@ -1 +1,2 @@
+Gemfile.lock
 slack_message*.gem

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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.
+
+## [2.3.1] - 2021-11-30
+- Adjust that minimum version by changing some syntax to older styles. Given
+  support for ruby 2.4 ended almost 2 years ago, going to go ahead and leave
+  it behind.
+- Remove lockfile from repo
+
 ## [2.3.0] - 2021-11-30
 - Formally require minimum version of ruby. It wouldn't have worked anyway,
   but worth actually specifying.

data/README.md

@@ -12,173 +12,14 @@ SlackMessage.post_to('#general') do
   text "We did it @here! :thumbsup:"
 end
 ```
+ 
+### The Docs
 
-To install, just add `slack_message` to your bundle and you're ready to go.
-
-#### Opinionated Stances
-
-Slack's API has a lot of options available to you! But this gem takes some
-opinionated stances about usage to try to minimize the pain of integrating
-with it. For example:
-
-* SlackMessage has no dependencies. Your lockfile is enough of a mess already.
-* 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.
-* Unless you request otherwise, text is always rendered using `mrkdwn`. If you
-  want plaintext, you'll need to ask for it. Same for the `emoji` flag.
-* As many API semantics as possible are hidden. For instance, if you post to
-  something that looks like an email address, `slack_message` is going to try
-  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.
-
-Usage
-------------
-
-### Configuration
-
-To get started, you'll 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 `users:read` and `chat:write`.
-
-```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. Most all have corresponding options when
-composing a message:
-
-| 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.
-
-### Posting Messages
-
-As mentioned at the top, 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 like this:
-
-```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"
-      }
-    ]
-  }
-]
-```
-
-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:
+You'll find much more information about how to use SlackMessage by visiting
+[the docs](https://jmmastey.github.io/slack_message).
+ 
 
-```ruby
-SlackMessage.post_to('hello@joemastey.com') do
-  text "You specifically did it! :thumbsup:"
-end
-```
+### Posting
 
 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
@@ -213,159 +54,42 @@ SlackMessage.post_to('#general') do
 end
 ```
 
-SlackMessage will compose this into Block Kit syntax and send it on its way!
-
-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
-```
-
-#### Notifying Users
-
-There are several supported ways to tag and notify users. Mentioned above, it's
-possible to DM a user by 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
-```
-
-### 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 like this, in your
-spec_helper file:
-
-```ruby
-require 'slack_message/rspec'
-
-RSpec.configure do |config|
-  include SlackMessage::RSpec
-
-  # your other 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.
-
-What it Doesn't Do
-------------
+### 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.
-If you want to add a feature, open an issue on Github first to see if it's
-likely to be merged. This gem was built out of an existing need that _didn't_
-include all of the block API, but I'd be inclined to merge features that
-sustainably expand the DSL to include more useful features.
+
+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.
+* Unless you request otherwise, text is always rendered using `mrkdwn`. If you
+  want plaintext, you'll need to ask for it. Same for the `emoji` flag.
+* As many API semantics as possible are hidden. For instance, if you post to
+  something that looks like an email address, `slack_message` is going to try
+  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 simple, with helpers for frequently reused bots.
 
 Some behaviors that are still planned but not yet added:
 
-* some API documentation amirite?
-* custom http_options in configuration
-* more of BlockKit's options
-* any interactive elements at all
-* editing / updating messages
-* multiple recipients
-* more interesting return types for your message
-* richer text formatting (for instance, `ul` is currently a hack)
-* more and better organized testing capability
+* 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)
+* posting ephemeral messages: https://api.slack.com/methods/chat.postEphemeral
 
-Contributing
-------------
+### Contributing
 
-Contributions are very welcome. Fork, fix, submit pull.
+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).
 
-License
-------------
+### 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,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)