slack_message 1.2.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f694caf399c0408dab35d5f63be0dc5a06b0c3611f3fd43a9533877f5ca7b1
-  data.tar.gz: 18a0dbd642a9b505ec21c114cf36fc36b9a4319c02a6f9fa057ac8abe6136957
+  metadata.gz: e66bdedefd2ac86c6c49d974e5f5d0474cc9b3756ce3a64e52df66ccc6e39cf4
+  data.tar.gz: b085edf556d957516d1cbbc9b260b7aff0e5d34b4561d27ae0d5f6b2dda9c93b
 SHA512:
-  metadata.gz: 2768ef640f9e2ba0d79227c14f38c4c3288a218464251be81d4f9d182814b1b4540588b16a834e1077d45ce77a82da716de63ebb4fd0de513a261f4da2dd5abf
-  data.tar.gz: a62d68742f30637398c4a337b9fd815c4b0f035aabe51a1d0be2693c3a72d2fbb8fcbe54cccd9c8e6983c44c1d199909f9e36792ba86d396764cf37549af2966
+  metadata.gz: ea935db68ca4771e11b40828d5cbd2fef02cf10c248fab3ede05ea82aef6a3a6d7ad96953debdc9214833ee0f281222e5e09adefd923c70d21090c996dba31a0
+  data.tar.gz: 46d2163aa9ec0e9df582700575d0c8b47b389b808f93275129025bc277086eb02fbeb4caa0754408dbc6d6fba9f06b6d8720493280550e0d3664bc735059f7c1

data/CHANGELOG.md

@@ -2,11 +2,26 @@
 
 ## [Unreleased]
 
+## [1.6.0] - 2021-10-04
+- Added `:default_channel` and `post_as` to deal with repetitive channel usage.
+
+## [1.5.0] - 2021-10-01
+- Added `ol` and `ul` to sections w/ some formatting.
+
+## [1.4.0] - 2021-09-27
+- Moved image to accessory_image to differentiate between the image block
+  and the accessory image within a block.
+
+## [1.3.0] - 2021-09-27
+- Added ability to use custom names when posting.
+- Added ability to post images within sections.
+- Added warnings for potentially invalid URLs.
+
 ## [1.2.0] - 2021-09-26
 - Turns out gemspec was broken. Fixed that.
 
 ## [1.1.0] - 2021-09-26
-- Expanded the README significantly w/ usage instructions
+- Expanded the README significantly w/ usage instructions.
 - Added lots of error handling to requests.
 
 ## [1.0.0] - 2021-09-25

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    slack_message (1.0.0)
+    slack_message (1.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,6 +6,14 @@ API](https://app.slack.com/block-kit-builder/) to make it easy to read and
 write messages to slack in your ruby application. It has zero dependencies and
 is built to be opinionated to keep your configuration needs low.
 
+Posting a message to Slack should be this easy:
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "We did it @here! :thumbsup:"
+end
+```
+
 To install, just add `slack_message` to your bundle and you're ready to go.
 
 
@@ -47,6 +55,28 @@ SlackMessage.configure do |config|
 end
 ```
 
+If you frequently ping the same channel with the same bot, and don't want to
+continually specify the channel name, you can specify a default channel and
+post using the `post_as` method. It is otherwise identical to `post_to`, but
+allows you to omit the channel argument:
+
+```ruby
+SlackMessage.configure do |config|
+  config.add_profile(:prod_alert_bot,
+    name: 'Prod Alert Bot',
+    url: ENV['SLACK_PROD_ALERT_WEBHOOK_URL'],
+    default_channel: '#red_alerts'
+  )
+end
+
+SlackMessage.post_as(:prod_alert_bot) do
+  text ":ambulance: weeooo weeooo something went wrong"
+end
+```
+
+Note that `post_as` does not allow you to choose a channel (because that's just
+the same as using `post_to`), so you really do have to specify `default_channel`.
+
 #### Configuring User Search
 
 Slack's API no longer allows you to send DMs to users by username. You need to
@@ -61,13 +91,13 @@ SlackMessage.configure do |config|
 end
 ```
 
-### Usage
+### Posting Messages
 
-Basic usage is pretty straightforward:
+As mentioned at the top, posting a message to Slack is dang easy:
 
 ```ruby
 SlackMessage.post_to('#general') do
-  text "We did it! :thumbsup:"
+  text "We did it @here! :thumbsup:"
 end
 ```
 
@@ -130,7 +160,7 @@ 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, see Slack's [Block Kit
 Builder](https://app.slack.com/block-kit-builder/) to understand the structure
-better:
+better. There are lots of options:
 
 ```ruby
 SlackMessage.post_to('#general') do
@@ -174,6 +204,27 @@ SlackMessage.post_to('#general', as: :sidekiq_bot) do
 end
 ```
 
+You can also use a custom name when sending a message:
+
+```ruby
+SlackMessage.post_to('#general') do
+  bot_name "CoffeeBot"
+
+  text ":coffee::clock: Time to take a break!"
+end
+```
+
+Opinionated Stances
+------------
+
+Slack's API has a lot of options available to you! But this gem takes some
+opinionated stances on how to make use of that API. For instance:
+
+* Unless you request otherwise, text is always rendered using `mrkdwn`. If you
+  want plaintext, you'll need to ask for it.
+* Generally, same goes for the `emoji` flag on almost every text element.
+* It's possible to ask for a `blank_line` in sections, even though that concept
+  isn't real. In this case, a text line containing only an emspace is rendered.
 
 What it Doesn't Do
 ------------
@@ -190,7 +241,11 @@ DSL to include more of the block API itself.
 Also, some behaviors that are still planned but not yet added:
 
 * allow custom http_options in configuration
-* allow custom slack username per built message
+* more of BlockKit's options
+* any interactive elements at all (I don't understand them yet)
+* more interesting return types for your message
+* some way to specify default channel for a given profile (and omit param to post_to)
+* richer text formatting (ul is currently a hack)
 
 Contributing
 ------------

data/lib/slack_message/configuration.rb

@@ -27,19 +27,21 @@ module SlackMessage::Configuration
 
   ###
 
-  def self.add_profile(handle = :default, name:, url:)
+  def self.add_profile(handle = :default, name:, url:, default_channel: nil)
     if @@profiles.include?(handle)
-      warn("WARNING: Overriding profile '#{handle}' in SlackMessage config")
+      warn "WARNING: Overriding profile '#{handle}' in SlackMessage config"
     end
 
-    @@profiles[handle] = { name: name, url: url, handle: handle }
+    @@profiles[handle] = { name: name, url: url, handle: handle, default_channel: default_channel }
   end
 
-  def self.profile(handle)
+  def self.profile(handle, custom_name: nil)
     unless @@profiles.include?(handle)
       raise ArgumentError, "Unknown SlackMessage profile '#{handle}'."
     end
 
-    @@profiles[handle]
+    @@profiles[handle].tap do |profile|
+      profile[:name] = custom_name if !custom_name.nil?
+    end
   end
 end

data/lib/slack_message/dsl.rb

@@ -1,9 +1,12 @@
 class SlackMessage::Dsl
-  attr_reader :body, :default_section
+  attr_reader :body, :default_section, :custom_bot_name
+
+  EMSPACE = " " # unicode emspace
 
   def initialize
     @body = []
     @default_section = Section.new
+    @custom_bot_name = nil
   end
 
   # allowable top-level entities within a block
@@ -24,6 +27,24 @@ class SlackMessage::Dsl
     @body.push({ type: "divider" })
   end
 
+  def image(url, alt_text:, title: nil)
+    finalize_default_section
+
+    config = {
+      type: "image",
+      image_url: url,
+      alt_text: alt_text,
+    }
+
+    if !title.nil?
+      config[:title] = {
+        type: "plain_text", text: title, emoji: true
+      }
+    end
+
+    @body.push(config)
+  end
+
   def context(text)
     finalize_default_section
 
@@ -38,12 +59,28 @@ class SlackMessage::Dsl
 
   def text(*args); default_section.text(*args); end
   def link_button(*args); default_section.link_button(*args); end
+  def accessory_image(*args); default_section.accessory_image(*args); end
   def blank_line(*args); default_section.blank_line(*args); end
   def link(*args); default_section.link(*args); end
   def list_item(*args); default_section.list_item(*args); end
+  def ul(*args); default_section.ul(*args); end
+  def ol(*args); default_section.ol(*args); end
 
   # end delegation
 
+  # custom bot name
+
+  def bot_name(name)
+    @custom_bot_name = name
+  end
+
+  # end bot name
+
+  def render
+    finalize_default_section
+    @body
+  end
+
   private
 
   # when doing things that would generate new top-levels, first try
@@ -56,11 +93,6 @@ class SlackMessage::Dsl
     @default_section = Section.new
   end
 
-  def render
-    finalize_default_section
-    @body
-  end
-
   class Section
     attr_reader :body
 
@@ -78,8 +110,31 @@ class SlackMessage::Dsl
       end
     end
 
+    def ul(elements)
+      raise Arguments, "please pass an array" unless elements.respond_to?(:map)
+      text(
+        elements.map { |text| "#{EMSPACE}• #{text}" }.join("\n")
+      )
+    end
+
+    def ol(elements)
+      raise Arguments, "please pass an array" unless elements.respond_to?(:map)
+      text(
+        elements.map.with_index(1) { |text, idx| "#{EMSPACE}#{idx}. #{text}" }.join("\n")
+      )
+    end
+
     # styles:  default, primary, danger
     def link_button(label, target, style: :primary)
+      if !@body[:accessory].nil?
+        previous_type = @body[:accessory][:type]
+        warn "WARNING: Overriding previous #{previous_type} in section to use link_button instead: #{label}"
+      end
+
+      unless /(^|\s)((https?:\/\/)?[\w-]+(\.[\w-]+)+\.?(:\d+)?(\/\S*)?)/i =~ target
+        warn "WARNING: Passing a probably-invalid URL to link button #{label} (url: '#{target}')"
+      end
+
       config = {
         accessory: {
           type: "button",
@@ -99,6 +154,24 @@ class SlackMessage::Dsl
       @body.merge!(config)
     end
 
+    def accessory_image(url, alt_text: nil)
+      if !@body[:accessory].nil?
+        previous_type = @body[:accessory][:type]
+        warn "WARNING: Overriding previous #{previous_type} in section to use accessory image instead: #{url}"
+      end
+
+      config = {
+        accessory: {
+          type: "image",
+          image_url: url
+        }
+      }
+
+      config[:accessory][:alt_text] = alt_text if !alt_text.nil?
+
+      @body.merge!(config)
+    end
+
     # for markdown links
     def link(label, target)
       "<#{target}|#{label}>"
@@ -109,7 +182,7 @@ class SlackMessage::Dsl
     end
 
     def blank_line
-      text " " # unicode emspace
+      text EMSPACE
     end
 
     def has_content?

data/lib/slack_message.rb

@@ -11,16 +11,35 @@ module SlackMessage
     configuration.configure(&block)
   end
 
-  def self.user_id_for(email)
+  def self.user_id_for(email) # spooky undocumented public method 👻
     Api::user_id_for(email)
   end
 
   def self.post_to(target, as: :default, &block)
-    payload = build(&block)
-    profile = Configuration.profile(as)
+    payload = Dsl.new.tap do |instance|
+      instance.instance_eval(&block)
+    end
+
+    profile = Configuration.profile(as, custom_name: payload.custom_bot_name)
+    target  = user_id_for(target) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
+
+    Api.post(payload.render, target, profile)
+  end
+
+  def self.post_as(profile_name, &block)
+    payload = Dsl.new.tap do |instance|
+      instance.instance_eval(&block)
+    end
+
+    profile = Configuration.profile(profile_name, custom_name: payload.custom_bot_name)
+    if profile[:default_channel].nil?
+      raise ArgumentError, "Sorry, you need to specify a default_channel for profile #{profile_name} to use post_as"
+    end
+
+    target  = profile[:default_channel]
     target  = user_id_for(target) if target =~ /^\S{1,}@\S{2,}\.\S{2,}$/
 
-    Api.post(payload, target, profile)
+    Api.post(payload.render, target, profile)
   end
 
   def self.build(&block)

data/slack_message.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name        = 'slack_message'
-  gem.version     = "1.2.0"
+  gem.version     = "1.6.0"
   gem.summary     = "A nice DSL for composing rich messages in Slack"
   gem.authors     = ["Joe Mastey"]
   gem.email       = 'hello@joemastey.com'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_message
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Joe Mastey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-26 00:00:00.000000000 Z
+date: 2021-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec