slack_message 2.2.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58dc8d1f101b642daabf6e686fc0e79973d73189acc3431f96d85de326d9c501
-  data.tar.gz: 68bd076ad93dc8cc4529be972968fbe5944fba78a8589938b8b2ab317d516b05
+  metadata.gz: 62f8b7feb3289a37b79cb887dc4e7846c037a8c72290138afe611682a066a884
+  data.tar.gz: 73e391d721ace67ad31ae69b7a17eae3578d4f85a2bcd111a5cb1966b68c85cd
 SHA512:
-  metadata.gz: d152ad36ec98acea2e85fb8c03be17aa180b291793e1028626dc7822142a218d493b64b9afda34e7b99a9ee3f795f2c5cff8ae75f53a9808857b128cf0efb708
-  data.tar.gz: 9bb12ce0e108c81a002afe44a4feb9d8879874705918d0d3fe5c5a263ef74b766272a5c28160cd5b62a8eea9ec85e2b6f37792257e2bfb0e436d83bac64bd9a6
+  metadata.gz: cb28febfda107047351955825d1cd84dafdf553147b9f0101573944f3d5290c6d3e84a4d1190e63888f6c8ba851ac70da9eb774f1a01a04372d19520b7df8779
+  data.tar.gz: 3438883916204aec8a16a8dfa80b52506d4f640fc69161ad6e8efea1b5a136e97fc15f8b990c2529f3bbfb1f4380a989a0827cbe8f810af08a42bf3a2b6df382

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, 2.4, 2.3]
+        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,24 @@
 # Changelog
 
+## [3.0.0] - 2021-12-19
+- Return a more structured object from successful message sends.
+- Add the ability to edit or delete a message.
+- Complete overhaul of docs because they were too large.
+
+## [2.4.0] - 2021-12-13
+- Add ability to schedule messages, plus some guard rails around that.
+- Add ability to debug by logging out the total set of params sent to the API.
+
+## [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.
+
 ## [2.2.2] - 2021-11-30
 - Add github workflow for automatic CI runs. Stolen from another project.
 

data/README.md

@@ -13,172 +13,7 @@ SlackMessage.post_to('#general') do
 end
 ```
 
-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:
-
-```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,155 +48,47 @@ SlackMessage.post_to('#general') do
 end
 ```
 
-SlackMessage will compose this into Block Kit syntax and send it on its way!
+### The Docs
 
-If you've defined multiple profiles in configuration, you can specify which to
-use for your message by specifying its name:
+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('#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.
+* 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.
 
 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
+* 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
+* posting ephemeral messages: https://api.slack.com/methods/chat.postEphemeral
+* some Rspec test harness for scheduled messages, editing, deleting (probably going to need a test overhaul)
 
 Contributing
 ------------
 
-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).
 

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)