slack_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d261d55e8623155c0593ad7759d93fac8d721d62dbbbfeb9f4f15769707e5334
+  data.tar.gz: 294c96bef43e20972a6cea6475c527c78a92e41792a6183703350657a576aff4
+SHA512:
+  metadata.gz: cad910618843bfa8f7b9e76275b6c9ec57216d9e5e67d3d04e038207f7f686e9ee8b4c93758033b4eb5c978b414f449810da62e81f20786e637c5c61183ccbca
+  data.tar.gz: 913cc697e863c83ecb5ffb4c5484509dcaea2dd275bb7105ec44d908b95c1076e44868ad5cadea86538754795d7b7021211d91e018792cb9a45e18c8a9930a15

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-08-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 cyb-
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# SlackBuilder
+
+![Version 0.1.0](https://img.shields.io/badge/Version-0.1.0-blue?logo=RubyGems&logoColor=%23E9573F)
+[![CircleCI](https://circleci.com/gh/cyb-/beta-app/tree/main.svg?style=shield&circle-token=a8ff610f989095686162e979db5babf49f34539b)](https://circleci.com/gh/cyb-/slack-builder/?branch=main)
+
+This gem aims to help generating [Slack](https://slack.com/) message payloads using [Block-kit API](https://api.slack.com/reference/block-kit/blocks) with kind of comfortable Ruby DSL focused on readability ¯\\_(ツ)_/¯
+
+### Available blocks
+
+|     | Block type                                                                | Available fields                                  |
+|-----|---------------------------------------------------------------------------|---------------------------------------------------|
+| ✅   | [`actions`](https://api.slack.com/reference/block-kit/blocks#actions)     | `elements`                                        |
+| ✅   | [`context`](https://api.slack.com/reference/block-kit/blocks#context)     | `elements`                                        |
+| ✅   | [`divider`](https://api.slack.com/reference/block-kit/blocks#divider)     | *N/A*                                             |
+| ❌   | [`file`](https://api.slack.com/reference/block-kit/blocks#file)           |                                                   |
+| ✅   | [`header`](https://api.slack.com/reference/block-kit/blocks#header)       | `text`                                            |
+| 🏗️ | [`image`](https://api.slack.com/reference/block-kit/blocks#image)         | `image_url`, `alt_text`, `title`                  |
+| ❌   | [`input`](https://api.slack.com/reference/block-kit/blocks#input)         |                                                   |
+| ✅   | [`rich_text`](https://api.slack.com/reference/block-kit/blocks#rich_text) | `elements`                                        |
+| ✅   | [`section`](https://api.slack.com/reference/block-kit/blocks#section)     | `text`, `fields`, `accessory`                     |                   
+| 🏗  | [`video`](https://api.slack.com/reference/block-kit/blocks#video)         | `video_url`, `thumbnail_url`, `alt_text`, `title` | 
+
+### Rich Text blocks
+
+|   | Block type                                                                                          | Available fields                        |
+|---|-----------------------------------------------------------------------------------------------------|-----------------------------------------|
+| ✅ | [`rich_text_section`](https://api.slack.com/reference/block-kit/blocks#rich_text_section)           | `elements`                              |
+| ✅ | [`rich_text_preformatted`](https://api.slack.com/reference/block-kit/blocks#rich_text_preformatted) | `elements`                              |
+| ✅ | [`rich_text_quote`](https://api.slack.com/reference/block-kit/blocks#rich_text_quote)               | `elements`                              |
+| ✅ | [`rich_text_list`](https://api.slack.com/reference/block-kit/blocks#rich_text_list)                 | `elements`, `style`, `indent`, `offset` |
+
+### Rich Text elements
+
+|   | Block type                                                                              | Available fields                         |
+|---|-----------------------------------------------------------------------------------------|------------------------------------------|
+| ✅ | [`broadcast`](https://api.slack.com/reference/block-kit/blocks#broadcast-element-type)  | `range`                                  |
+| ✅ | [`channel`](https://api.slack.com/reference/block-kit/blocks#channel-element-type)      | `channel_id`, `style`                    |
+| ✅ | [`color`](https://api.slack.com/reference/block-kit/blocks#color-element-type)          | `value`                                  |
+| ✅ | [`date`](https://api.slack.com/reference/block-kit/blocks#date-element-type)            | `timestamp`, `format`, `url`, `fallback` |
+| ✅ | [`emoji`](https://api.slack.com/reference/block-kit/blocks#emoji-element-type)          | `name`                                   |
+| ✅ | [`link`](https://api.slack.com/reference/block-kit/blocks#link-element-type)            | `text`, `url`, `unsafe`, `style`         |
+| ✅ | [`text`](https://api.slack.com/reference/block-kit/blocks#text-element-type)            | `text`, `style`                          |
+| ✅ | [`user`](https://api.slack.com/reference/block-kit/blocks#user-element-type)            | `user_id`, `style`                       |
+| ✅ | [`usergroup`](https://api.slack.com/reference/block-kit/blocks#user-group-element-type) | `usergroup_id`, `style`                  |
+
+### Interactive elements
+
+|    | Block type                                                                  | Available fields                                           |
+|----|-----------------------------------------------------------------------------|------------------------------------------------------------|
+| 🏗 | [`button`](https://api.slack.com/reference/block-kit/block-elements#button) | `text`, `url`, `action_id`, `style`, `accessibility_label` |
+
+
+## Installation
+
+> [!WARNING]
+> Gem is going to be released on [RubyGems](https://rubygems.org/) soon.
+
+Until the first release, you can install it from the Github repository using the `main` branch.
+
+```ruby
+gem 'slack_builder', git: 'https://github.com/cyb-/slack-builder.git', branch: 'main', require: false
+```
+
+
+## Usage
+
+Please refer to the **Slack API Block-kit** [documentation](https://api.slack.com/reference/block-kit/blocks) for available blocks and options.
+
+```ruby
+require 'slack_builder'
+
+SlackBuilder.message do
+  header 'Hello world :wave:'
+  divider
+  context do
+    mrkdwn '*`Hello`* <https://example.com|world> :wave:'
+  end
+  image 'https://media.giphy.com/media/AcfTF7tyikWyroP0x7/giphy.gif', alt_text: 'Foo', title: 'Blob :ok_hand:', emoji: false
+  divider
+  section '*`Hello`* <https://example.com|world> :wave:' do
+    mrkdwn '*Priority*'
+    mrkdwn '*Critical*'
+    plain_text 'High :collision:'
+    plain_text '¯\\_(ツ)_/¯', emoji: false
+    accessory do
+      image 'https://media.giphy.com/media/cYNjbM2MvPzM8raKvh/giphy.gif', alt_text: 'Bar'
+    end
+  end
+  video 'https://www.youtube.com/watch?v=PdaAHMztNVE', thumbnail_url: 'https://media.giphy.com/media/cYNjbM2MvPzM8raKvh/giphy.gif', alt_text: 'Foo', title: 'Bar :collision:'
+  divider
+  rich_text do
+    section do
+      text 'Hello', bold: true, code: true
+      link 'world', url: 'https://example.com'
+      emoji :wave
+    end
+    quote do
+      text 'Woopsie'
+      broadcast :channel
+      color '#666'
+    end
+    list :bullet do
+      section do
+        usergroup SLACK_USERGROUP_ID, client_highlight: true, highlight: true, italic: true
+      end
+      section do
+        channel SLACK_CHANNEL_ID, client_highlight: true, bold: true, strike: true
+        date 42, format: '{day_divider_pretty}', url: 'https://example.com'
+      end
+    end
+    list :ordered, indent: 1 do
+      section do
+        text 'Hello'
+      end
+      section do
+        text 'world'
+      end
+    end
+    list :bullet do
+      section do
+        emoji :wave
+      end
+    end
+    preformatted do
+      text 'Hello', italic: true
+      user SLACK_USER_ID, unlink: true, highlight: true, bold: true
+    end
+  end
+  divider
+  actions do
+    button 'Click me :bomb:', url: 'https://github.com/cyb-/slack-builder', style: :danger
+  end
+end
+```
+
+You can also optionally add [secondary attachments](https://api.slack.com/reference/messaging/attachments) to your message, with an optional color
+
+```ruby
+require 'slack_builder'
+
+SlackBuilder.message do
+  header 'Hello world :wave:'
+  
+  attachment color: '#666' do
+    rich_text do
+      section do
+        text 'Woopsie'
+        emoji :grimacing
+      end
+    end
+  end
+end
+```
+
+Or with a text
+
+```ruby
+require 'slack_builder'
+
+SlackBuilder.message '*`Hello`* <https://example.com|world> :wave:' do
+  header 'Hello world :wave:'
+  
+  attachment do
+    rich_text do
+      section do
+        emoji :bomb
+      end
+    end
+  end
+end
+```
+
+### Sending message
+
+> [!NOTE]
+> Gem has no dependencies, it's up to you to send the message however you want ¯\\_(ツ)_/¯
+
+#### Example using [Slack client](https://github.com/slack-ruby/slack-ruby-client)
+```ruby
+require 'slack_builder'
+
+payload = SlackBuilder.message do
+  # ...
+end
+  
+client = Slack::Web::Client.new
+client.chat_postMessage(channel: '#somewhere', as_user: true, **payload)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cyb-/slack-builder/issues.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/slack_builder/attachment.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'elements/base/concerns/has_elements'
+require_relative 'elements/actions'
+require_relative 'elements/divider'
+require_relative 'elements/header'
+require_relative 'elements/image'
+require_relative 'elements/context'
+require_relative 'elements/rich_text'
+require_relative 'elements/section'
+require_relative 'elements/video'
+
+module SlackBuilder
+  class Attachment
+    include Elements::Base::Concerns::HasElements
+
+    def initialize(color: nil, &blk)
+      @color = color.to_s unless color.nil?
+      super(&blk)
+    end
+
+    def to_h
+      { blocks: to_a }.tap do |h|
+        h[:color] = @color if defined?(@color)
+      end
+    end
+
+    def actions(...)
+      add Elements::Actions.new(...) if block_given?
+    end
+
+    def context(...)
+      add Elements::Context.new(...) if block_given?
+    end
+
+    def divider(...)
+      add Elements::Divider.new(...)
+    end
+
+    def header(...)
+      add Elements::Header.new(...)
+    end
+
+    def image(...)
+      add Elements::Image.new(...)
+    end
+
+    def rich_text(...)
+      add Elements::RichText.new(...) if block_given?
+    end
+
+    def section(...)
+      add Elements::Section.new(...)
+    end
+
+    def video(...)
+      add Elements::Video.new(...)
+    end
+  end
+end

data/lib/slack_builder/elements/actions.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+require_relative 'base/concerns/has_elements'
+require_relative 'interactive_elements/button'
+
+module SlackBuilder
+  module Elements
+    class Actions < Base::Element
+      include Base::Concerns::HasElements
+
+      TYPE = 'actions'
+
+      def button(...)
+        add InteractiveElements::Button.new(...)
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/base/concerns/has_elements.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../element'
+
+module SlackBuilder
+  module Elements
+    module Base
+      module Concerns
+        module HasElements
+          ELEMENTS_KEY_NAME = :elements
+
+          def initialize(*args, **kwargs, &blk)
+            @elements = []
+            super(*args, **kwargs)
+            append(&blk)
+          end
+
+          def to_a
+            @elements.map(&:to_h)
+          end
+
+          def to_ary
+            to_a
+          end
+
+          def empty?
+            @elements.empty?
+          end
+
+          def any?
+            !empty?
+          end
+
+          def to_h
+            super.merge(self.class::ELEMENTS_KEY_NAME => to_a)
+          end
+
+          def to_hash
+            to_h
+          end
+
+          def as_json(*)
+            to_h
+          end
+
+          def append(&blk)
+            instance_exec(&blk) if block_given?
+          end
+
+          private
+
+          def add(element)
+            raise ArgumentError, 'Invalid element' unless element.is_a?(Element)
+
+            @elements << element
+            element
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/base/element.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SlackBuilder
+  module Elements
+    module Base
+      class Element
+        attr_reader :block_id
+
+        def initialize(block_id: nil)
+          @block_id = block_id unless block_id.nil?
+        end
+
+        def type
+          self.class::TYPE
+        end
+
+        def to_h
+          { type: type, block_id: block_id }.compact
+        end
+
+        def to_hash
+          to_h
+        end
+
+        def as_json(*)
+          to_h
+        end
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/base/text.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'element'
+
+module SlackBuilder
+  module Elements
+    module Base
+      class Text < Element
+        def initialize(text, ...)
+          @text = text
+          super(...)
+        end
+
+        def to_h
+          super.merge(text: @text)
+        end
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+require_relative 'base/concerns/has_elements'
+require_relative 'text_elements/markdown'
+require_relative 'text_elements/plain_text'
+require_relative 'image'
+
+module SlackBuilder
+  module Elements
+    class Context < Base::Element
+      include Base::Concerns::HasElements
+
+      TYPE = 'context'
+
+      def image(...)
+        add Image.new(...)
+      end
+
+      def mrkdwn(...)
+        add TextElements::Markdown.new(...)
+      end
+
+      def plain_text(...)
+        add TextElements::PlainText.new(...)
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/divider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+
+module SlackBuilder
+  module Elements
+    class Divider < Base::Element
+      TYPE = 'divider'
+    end
+  end
+end

data/lib/slack_builder/elements/header.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+require_relative 'text_elements/plain_text'
+
+module SlackBuilder
+  module Elements
+    class Header < Base::Element
+      TYPE = 'header'
+
+      def initialize(text, emoji: true, **kwargs)
+        @text = TextElements::PlainText.new(text, emoji: emoji)
+        super(**kwargs)
+      end
+
+      def to_h
+        super.merge(text: @text.to_h)
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/image.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+require_relative 'text_elements/plain_text'
+
+module SlackBuilder
+  module Elements
+    class Image < Base::Element
+      TYPE = 'image'
+
+      def initialize(image_url, alt_text:, title: nil, emoji: true, **kwargs)
+        @image_url = image_url
+        @alt_text = alt_text
+        @title = TextElements::PlainText.new(title, emoji: emoji) unless title.nil?
+        super(**kwargs)
+      end
+
+      def to_h
+        super.merge(image_url: @image_url, alt_text: @alt_text).tap do |h|
+          h[:title] = @title.to_h if defined?(@title)
+        end
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/interactive_elements/button.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../base/element'
+require_relative '../text_elements/plain_text'
+
+module SlackBuilder
+  module Elements
+    module InteractiveElements
+      class Button < Base::Element
+        TYPE = 'button'
+
+        def initialize(text, url:, style: nil, emoji: true, action_id: nil, accessibility_label: nil, **kwargs)
+          @text = TextElements::PlainText.new(text, emoji: emoji)
+          @url = url
+          @style = style.to_s unless style.nil?
+          @action_id = action_id unless action_id.nil?
+          @accessibility_label = accessibility_label unless accessibility_label.nil?
+          super(**kwargs)
+        end
+
+        def to_h
+          super.merge(text: @text.to_h, url: @url).tap do |h|
+            h[:style] = @style if defined?(@style)
+            h[:action_id] = @action_id if defined?(@action_id)
+            h[:accessibility_label] = @accessibility_label if defined?(@accessibility_label)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slack_builder/elements/rich_text.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'base/element'
+require_relative 'base/concerns/has_elements'
+require_relative 'rich_text_elements/broadcast'
+require_relative 'rich_text_elements/channel'
+require_relative 'rich_text_elements/color'
+require_relative 'rich_text_elements/date'
+require_relative 'rich_text_elements/emoji'
+require_relative 'rich_text_elements/link'
+require_relative 'rich_text_elements/text'
+require_relative 'rich_text_elements/user'
+require_relative 'rich_text_elements/usergroup'
+
+module SlackBuilder
+  module Elements
+    class RichText < Base::Element
+      include Base::Concerns::HasElements
+
+      TYPE = 'rich_text'
+
+      module HasBorder
+        def initialize(border: nil, **kwargs, &blk)
+          @border = border unless border.nil?
+          super(**kwargs, &blk)
+        end
+
+        def to_h
+          super.tap do |h|
+            h[:border] = @border if defined?(@border)
+          end
+        end
+      end
+
+      class Section < Base::Element
+        include Base::Concerns::HasElements
+
+        TYPE = 'rich_text_section'
+
+        def broadcast(...)
+          add RichTextElements::Broadcast.new(...)
+        end
+
+        def channel(...)
+          add RichTextElements::Channel.new(...)
+        end
+
+        def color(...)
+          add RichTextElements::Color.new(...)
+        end
+
+        def date(...)
+          add RichTextElements::Date.new(...)
+        end
+
+        def emoji(...)
+          add RichTextElements::Emoji.new(...)
+        end
+
+        def link(...)
+          add RichTextElements::Link.new(...)
+        end
+
+        def text(...)
+          add RichTextElements::Text.new(...)
+        end
+
+        def user(...)
+          add RichTextElements::User.new(...)
+        end
+
+        def usergroup(...)
+          add RichTextElements::Usergroup.new(...)
+        end
+      end
+
+      class Preformatted < Section
+        include HasBorder
+
+        TYPE = 'rich_text_preformatted'
+      end
+
+      class Quote < Section
+        include HasBorder
+
+        TYPE = 'rich_text_quote'
+      end
+
+      class List < Base::Element
+        include Base::Concerns::HasElements
+        include HasBorder
+
+        TYPE = 'rich_text_list'
+
+        def initialize(style, indent: nil, offset: nil, **kwargs, &blk)
+          @style = style&.to_s
+          @indent = indent unless indent.nil?
+          @offset = offset unless offset.nil?
+          super(**kwargs, &blk)
+        end
+
+        def to_h
+          super.merge(style: @style).tap do |h|
+            h[:indent] = @indent if defined?(@indent)
+            h[:offset] = @offset if defined?(@offset)
+          end
+        end
+
+        def section(...)
+          add Section.new(...) if block_given?
+        end
+      end
+
+      protected
+
+      def section(...)
+        add Section.new(...) if block_given?
+      end
+
+      def preformatted(...)
+        add Preformatted.new(...) if block_given?
+      end
+
+      def quote(...)
+        add Quote.new(...) if block_given?
+      end
+
+      def list(...)
+        add List.new(...) if block_given?
+      end
+    end
+  end
+end