slack_bot-events 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26e9e0a0edd93455cbc0cff5043f9a5e9a93a1bdb1a6ace9107df71cabd01856
-  data.tar.gz: 4eb9d15cc14f868f8e1f8bab0ccaaca876e256899a84d2b53cf5939df2496205
+  metadata.gz: 4db0e3fd554d51024ebf0d4c1b6d63856ccd4d72c6c83901d0542926db70c2ac
+  data.tar.gz: 154cc348c600534eda58f68d3b66bcae1ef924f73964f9787e98fc18882c363c
 SHA512:
-  metadata.gz: 44891a0644cd45f3b8c22a8256f48e509933b7a35a4504f9ac046d8b761fcd5a8bee09d2ecefa89d85616953e7a70e18b7fc84a1a5435a97f4d5dc4eb2fbcef2
-  data.tar.gz: 8af558314cab90d174ac1555f590eaeaab3bd87530928da99eea571486c962ef2926f41d82ff030107fc4ad4d615a7835030579b5497970bfd65a3653ec8991d
+  metadata.gz: 6dca807680fbd02f2c8ce30ba2a019c03e5acf47373fbc73133ff61fcd981973f3bee7b1257f014d1b1d05bb46b1af92a8e07336186a3a20118a851ffe8713f3
+  data.tar.gz: 52449fa2a7f111fd5dc06fd605995bac87994822dda2e483d0ab012a2df330d25bd22e42692b0428f6967340a99b1fa4e71a5c0dccb4475abcd4b124b15d3ba6

data/.gitignore

@@ -18,3 +18,7 @@
 # generated gems
 *.gem
 .env
+
+# Example Gemfiles
+/examples/**/Gemfile.lock
+

data/README.md

@@ -0,0 +1,125 @@
+# SlackBot Events
+
+Welcome to SlackBot Events Gem! This gem provides a seamless way to hook into your paid Slack Workspace's Events API and run complex or simple automation. You can run automations based on events like: Message Deleted, Reactions Added, Reactions Removed, Message sent to channel, Message sent to Thread, User added to Channel, and so many more. [View Full list of Events Here](https://api.slack.com/events).
+
+SlackBot Events provides the foundational tooling to run a SlackBot, automate Jira tickets based on Events, Customize and Automate AI responses to messages, Automate tagging relavant groups in threads, track time to respond and time to resolve threads, and so much more.
+
+SlackBot Events Gem connects directly into your paid Slack workspace by utilizing websockets. Websockets provides a resilient, safe, and reliable connection to retreive events without the need to expose a public endpoint for Slack Events.
+
+## Installation
+
+```ruby
+source 'http://rubygems.org'
+gem 'slack_bot-events'
+```
+
+[Example Use Cases](/examples)
+
+## SlackBot Events inspiration
+
+There already exists No to Low code Slack workflow Engines like Zappier. However, these workflows are often slow and buggy. They cost money based on usage. Additionally, creating complex workflows with low code is a bit messy.
+
+SlackBot Events provides a free alternative to exposing events from your paid Slack Workspace.
+
+## Configuration
+
+### Required Slack Bot Configuration
+This bit is rather boring. Check out the [Boring Slack Configuration Setup](/boring_slack_configuration.md). You will need the App Level Token for the next step
+
+### Required ENV variables:
+`SLACK_SOCKET_TOKEN` is the only ENV variable that is required for this Gem. Using the token that was saved from an earlier step, set the token to the ENV variable `SLACK_SOCKET_TOKEN`. There is an alternate assignment option below.
+
+### Configuration Options:
+``` ruby
+SlackBot::Events.configure do |config|
+  # This token is needed to retreive a WebSocket connection to the Events API
+  # Default value: ENV["SLACK_SOCKET_TOKEN"]
+  config.client_socket_token = "AppLevelToken"
+
+  # By default, SlackBot::Events will print out a TLDR of every events message that comes through
+  # Default value: true
+  config.print_tldr = true
+
+  # By default, SlackBot::Events will acknowledge at the end of the middleware chain after it passes the message to the event listener. Available options:
+  # => on_complete: Acknowledge after listener has completed on failure and on success
+  # => on_success: Acknowledge only on succesful listener events (Use with caution)
+  # => on_receive: Acknowledge at the beginning of the middleware chain before it gets to listener events
+  # Default value: :on_complete
+  config.envelope_acknowledge = :on_complete
+
+  # By default, this gem outputs to STDOUT. You can set your own logger ot set it to the Rails logger if desired
+  # Default value: Logger.new(STDOUT)
+  config.logger = Rails.logger
+end
+```
+
+### Event Listeners:
+Event Listeners is where the configurable power comes in. Listeners are custom code that gets run on specific event_api actions as defined in [Slack Event Types](https://api.slack.com/events).
+
+There can be at most 1 configured listener listeing to any given event type.
+
+To Register a new listener:
+```ruby
+SlackBot::Events.register_listener(name: "event_type_name", handler: handler_object)
+SlackBot::Events.register_listener(name: "event_type_name_2", handler: handler_object2, on_success: on_success_proc)
+SlackBot::Events.register_listener(name: "event_type_name_3", handler: handler_object3, on_failure: on_failure_proc)
+
+### Or via the config
+
+SlackBot::Events.configure do |c|
+  c.register_listener(name: "event_type_name4", handler: handler_object4)
+end
+
+```
+
+#### Handler
+The Handler argument must be an object that responds to `call` with KWargs `schema` and `raw_data`.
+
+#### On Failure (Optional Argument)
+The `on_failure` argument must be an object that resoonds to `call` with 2 arguments. The first argument will be the converted schema if available. The second argument will be the error that caused the Handler to fail
+
+#### On Success (Optional Argument)
+The `on_success` argument must be an object that resoonds to `call` with 1 argument. The argument will be the converted schema if available.
+
+[Example with Basic Listeners](/examples/basic)
+
+[Example with Multiple Listeners](/examples/multi_listener)
+
+## Middleware
+
+Middlewares can help add additional observability into a unit of work. For the Websocket message type, you can add any number of middlewars via the Configure block.
+
+
+```ruby
+SlackBot::Events.configure do |c|
+  c.message_middleware.add(DataDogObeservabilityMiddleware)
+end
+```
+
+## Known Restrictions
+### Limited number of events per hour per workspace
+[Slack Events API](https://api.slack.com/apis/rate-limits#events) has a limit of 30,000 events sent per hour per workspace. When this limit is hit, Slack will send the message type `app_rate_limited`.
+
+You can see an example of how this can get handled in the [EventTracer Middleware](lib/slack_bot/events/middleware/event_tracer.rb)
+
+
+### 10 open Sockets per App
+A Slack app can have at most 10 open sockets to Slack simultaneously. On WebSocket aquisition, it will first send the `open` type. This will reveal how many open connections there currently are.
+
+In regards to SlackBot::Events, this limitation means that you can have at most 10 instances of SlackBot::Events running per bod.
+
+For more information, Visit [Using Multiple Connections](https://api.slack.com/apis/socket-mode#connections) on Slack API page
+
+### Message Acknowledgment
+`SlackBot::Events` by default will handle message acknowledgment on your behalf. This can get taken care of before or after the handler is executed.
+
+Slack expects an Aknowledgment within 3 seconds. If your Middleware combined with the handler execution takes longer than the expected 3 seconds, Slack will immediately attempt to send the same envelope package again. This will cause duplication in your application.
+
+Retry attempts can occur on any open socket.
+- Attempt 3 Seconds after no response
+- Attempt 60 Seconds after no response
+- Attempt 5 minutes after no response
+
+Over the course of an hour, if you fail to send acknowledgement before the first retry, you will be rate limited and your app cordoned off
+
+Ideally, your listener executes quickly and returns. This means your execution is quick or you ship the data off to an async job like Sidekiq or spawn a new thread.

data/boring_slack_configuration.md

@@ -0,0 +1,39 @@
+# Slack Bot Requirements:
+SlackBot::Events gem utilizes the [Slack Events API](https://api.slack.com/apis/events-api) with Socket Mode. Events are pushed directly to any socket that is open and accepting requets.
+
+**Warning** This Slack Bot requires the ability to connect to the events API using a WebSocket. This is only available in paid workspaces and development workspaces. Not available in free Workspaces.
+
+You will need:
+## Slack App created
+To create a Slack App, checkout out [Slacks App Quickstart Guide](https://api.slack.com/quickstart). If you are familiar with Slack App Creation, you can go directly to the [Slack Apps Homepage](https://api.slack.com/apps)
+
+## Slack App Socket Enable
+SlackBot::Events is based on Socket mode. Socket mode must get enabled before you can subscribe to events without a `Request URL` public endpoint in your application.
+
+Navigate to your app and select the `Socket Mode` tab on the left. Ensure the switch to `Enable Socket Mode` is toggled on before proceeding
+
+You will be asked to create a new token. Name it whatever you would like. This will create a new token for you.
+
+You will **NEED** to retain the token for this Gem. (But don't worry, you can create a new one using with [Slack App Level tokens](https://api.slack.com/concepts/token-types#app-level) later as well)
+
+## Slack App Events received
+Every workpace has a limitation on the number of events the entire workspace can receive. This means that you should choose carefully which events your App can recieve.
+
+Navigate to your app and select the `Event Subscriptions` tab on the left.
+
+Carefully pick the events to subscribe to under the `Subscribe to bot events`.
+
+A good place to start is by subscribing to the following events:
+```
+message.channels
+reaction_added
+reaction_removed
+```
+*Note*: This will automatically add the correct OAuth permissions to the bot user. When you want to add additional subscriptions, come back here.
+
+## Install the Slack app to your workspace
+Navigate to your app and select the `Install App` tab on the left. Click on `Install to Workspace`. In some cases, you may need to get Workspace Admin approval before the app becomes available in the workspace.
+
+## Add the Bot to specific Channels
+Once the App is intalled into the workspace, invite the new bot to channels. Once the bot is in a channel, it will have the ability to send subscribed events to SlackBot::Events gem
+

data/changelog.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.4.4
+- Introduce Changelog
+- Introduce Example workflows
+- Introduce Readme
+

data/examples/README.md

@@ -0,0 +1,30 @@
+# Examples
+This is the root directory for examples. Provided you have the correct `SLACK_SOCKET_TOKEN` ENV variable created, these examples will work with your workspace.
+
+## [Basic Example](/examples/basic)
+```bash
+cd basic
+bundle i
+ruby main.rb
+```
+
+## [Middleware Example](/examples/middleware)
+```bash
+cd middleware
+bundle i
+ruby main.rb
+```
+
+## [Middleware No Yield Example](/examples/middleware_no_yield)
+```bash
+cd middleware_no_yield
+bundle i
+ruby main.rb
+```
+
+## [Multi Listener Example](/examples/multi_listener)
+```bash
+cd multi_listener
+bundle i
+ruby main.rb
+```

data/examples/basic/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+source 'http://rubygems.org'
+
+gem 'slack_bot-events', path: '../..'

data/examples/basic/main.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require "slack_bot-events"
+require_relative "message_listener.rb"
+
+# The `name` must match a Event subscription type found
+# https://api.slack.com/events
+
+# Register a listener for all reaction removed events
+SlackBot::Events.register_listener(
+  name: "message",
+  # Handler must respond to call with schema: and raw_data: KWARGS
+  handler: MessageListener,
+  # on_success must respond to call with 1 arg of schema
+  on_success: MessageListener.method(:on_success),
+  # on_failure must respond to call with 2 args of schema and error
+  on_failure: MessageListener.method(:on_failure),
+)
+
+
+# This is a blocking way to start the Websocket client
+# EventMachine is used to keep the socket open
+# The process responds to all SigQuit/Term/Kill events as expected
+SlackBot::Events::Client.new.start!

data/examples/basic/message_listener.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MessageListener
+  def self.call(schema:, raw_data:)
+    # Do some cool(quick returning) things here
+    # schema.payload.event will be a SlackBot::Events::Schemas::Type::Message
+    puts "Heya! I found a message! #{schema.payload.event.text}"
+    raise StandardError, "I Randomly decided to Barf" if rand > 0.9
+  end
+
+  def self.on_success(schema)
+    # Send a metric maybe?
+    # Or a Log Message
+    puts "Congrats! You executed it succesfully"
+  end
+
+  def self.on_failure(schema, error)
+    # Send job to sidekiq to try again?
+    # Or send a log message; but make sure to do it quick
+    puts "Yikes, You died a misreable death"
+  end
+end

data/examples/middleware/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+source 'http://rubygems.org'
+
+gem 'slack_bot-events', path: '../..'

data/examples/middleware/main.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require "slack_bot-events"
+require_relative "message_listener.rb"
+require_relative "meddling_message_middleware.rb"
+
+SlackBot::Events.configure do |c|
+  c.message_middleware.add(MeddlingMessageMiddleware)
+  c.print_tldr = false
+end
+
+SlackBot::Events.register_listener(
+  name: "message",
+  handler: MessageListener,
+  on_success: MessageListener.method(:on_success),
+  on_failure: MessageListener.method(:on_failure),
+)
+
+SlackBot::Events::Client.new.start!

data/examples/middleware/meddling_message_middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class MeddlingMessageMiddleware
+  # Message middlewares have the following KWargs available to them
+
+  # parsed_data => Raw JSON of schema
+  # schema => Schematized objected of data. schema.payload.event has much of the data you will want to mess with
+  # socket_event => The socket_event object that was given -- Unlikely you need to play with this
+  # listener => { handler:, on_success:, on_failure: } if the listener exists for the schema type; will be nil otherwise
+  # type => will be one of :message, :ope, :close
+  # websocket => The websocket client attached to Slack
+  def call(parsed_data:, schema:, socket_event:, listener:, type:, websocket:)
+    ###
+    # Code to execute BEFORE the listener handler is called
+    ###
+    puts "I get called BEFORE the Handler gets executed"
+
+
+
+    # The middleware chain is broken if yield is not called
+    # If provided, the listener handler will not get called either
+    # There may be occasions when you want to halt the middleware chain, but
+    # for the most part, ensure you always yield
+    yield
+
+
+
+    ###
+    # Code to execute AFTER the listener handler is called
+    ###
+    puts "I get called AFTER the Handler gets executed"
+  end
+end

data/examples/middleware/message_listener.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MessageListener
+  def self.call(schema:, raw_data:)
+    # Do some cool(quick returning) things here
+    # schema.payload.event will be a SlackBot::Events::Schemas::Type::Message
+    puts "Heya! I found a message! #{schema.payload.event.text}"
+    raise StandardError, "I Randomly decided to Barf" if rand > 0.9
+  end
+
+  def self.on_success(schema)
+    # Send a metric maybe?
+    # Or a Log Message
+    puts "Congrats! You executed it succesfully"
+  end
+
+  def self.on_failure(schema, error)
+    # Send job to sidekiq to try again?
+    # Or send a log message; but make sure to do it quick
+    puts "Yikes, You died a misreable death"
+  end
+end

data/examples/middleware_no_yield/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+source 'http://rubygems.org'
+
+gem 'slack_bot-events', path: '../..'

data/examples/middleware_no_yield/main.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require "slack_bot-events"
+require_relative "message_listener.rb"
+require_relative "meddling_message_middleware.rb"
+
+SlackBot::Events.configure do |c|
+  c.message_middleware.add(MeddlingMessageMiddleware)
+  c.print_tldr = false
+end
+
+SlackBot::Events.register_listener(
+  name: "message",
+  handler: MessageListener,
+  on_success: MessageListener.method(:on_success),
+  on_failure: MessageListener.method(:on_failure),
+)
+
+SlackBot::Events::Client.new.start!

data/examples/middleware_no_yield/meddling_message_middleware.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class MeddlingMessageMiddleware
+  # Message middlewares have the following KWargs available to them
+  def call(parsed_data:, schema:, socket_event:, listener:, type:, websocket:)
+    puts "I get called BEFORE the Handler gets executed"
+
+    puts "But wait! There is no yield, Message Handler never gets called"
+  end
+end

data/examples/middleware_no_yield/message_listener.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MessageListener
+
+  def self.call(schema:, raw_data:)
+    raise "Its okay, It never actually makes it here"
+  end
+
+  def self.on_success(schema)
+    # Send a metric maybe?
+    # Or a Log Message
+    puts "I did still make it to the on_success handler"
+  end
+
+  def self.on_failure(schema, error)
+    # Send job to sidekiq to try again?
+    # Or send a log message; but make sure to do it quick
+    puts "Yikes, You died a misreable death"
+  end
+end

data/examples/multi_listener/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+source 'http://rubygems.org'
+
+gem 'slack_bot-events', path: '../..'

data/examples/multi_listener/main.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require "slack_bot-events"
+require_relative "message_listener.rb"
+require_relative "reaction_removed_listener.rb"
+
+# The `name` must match a Event subscription type found
+# https://api.slack.com/events
+
+###
+# In the examples below, on_success and on_failure are methods
+# They can be left empty or a be a proc
+###
+
+# Register a listener for all reaction removed events
+SlackBot::Events.register_listener(
+  name: "reaction_removed",
+  # Handler must respond to call with schema: and raw_data: KWARGS
+  handler: ReactionRemovedListener,
+  # on_success must respond to call with 1 arg of schema
+  on_success: ReactionRemovedListener.method(:on_success),
+  # on_failure must respond to call with 2 args of schema and error
+  on_failure: ReactionRemovedListener.method(:on_failure),
+)
+
+# Register a listener for all messages sent to a channel the bot is added to
+SlackBot::Events.register_listener(
+  name: "message",
+  # Handler must respond to call with schema: and raw_data: KWARGS
+  handler: MessageListener,
+  # on_success must respond to call with 1 arg of schema
+  on_success: MessageListener.method(:on_success),
+  # on_failure must respond to call with 2 args of schema and error
+  on_failure: MessageListener.method(:on_failure),
+)
+
+# This is a blocking way to start the Websocket client
+# EventMachine is used to keep the socket open
+# The process responds to all SigQuit/Term/Kill events as expected
+SlackBot::Events::Client.new.start!

data/examples/multi_listener/message_listener.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MessageListener
+
+  def self.call(schema:, raw_data:)
+    # Do some cool(quick returning) things here
+    # schema.payload.event will be a SlackBot::Events::Schemas::Type::Message
+    puts "Heya! I found a message! #{schema.payload.event.text}"
+    raise StandardError, "I Randomly decided to Barf" if rand > 0.9
+  end
+
+  def self.on_success(schema)
+    # Send a metric maybe?
+    # Or a Log Message
+    puts "Congrats! You executed it succesfully"
+  end
+
+  def self.on_failure(schema, error)
+    # Send job to sidekiq to try again?
+    # Or send a log message; but make sure to do it quick
+    puts "Yikes, You died a misreable death"
+  end
+end

data/examples/multi_listener/reaction_removed_listener.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ReactionRemovedListener
+
+  def self.call(schema:, raw_data:)
+    # Do some cool(quick returning) things here
+    # schema.payload.event will be a SlackBot::Events::Schemas::Type::ReactionModified
+    puts "Heya! I found a reaction! #{schema.payload.event.reaction}"
+    raise StandardError, "I Randomly decided to Barf" if rand > 0.9
+  end
+
+  def self.on_success(schema)
+    # Send a metric maybe?
+    # Or a Log Message
+    puts "Congrats! You executed it succesfully"
+  end
+
+  def self.on_failure(schema, error)
+    # Send job to sidekiq to try again?
+    # Or send a log message; but make sure to do it quick
+    puts "Yikes, You died a misreable death"
+  end
+end

data/lib/slack_bot/events/version.rb

@@ -2,6 +2,6 @@
 
 module SlackBot
   module Events
-    VERSION = "0.4.2"
+    VERSION = "0.4.4"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_bot-events
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-21 00:00:00.000000000 Z
+date: 2024-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -129,7 +129,25 @@ files:
 - bin/console
 - bin/setup
 - bin/start
+- boring_slack_configuration.md
+- changelog.md
 - docker-compose.yml
+- examples/README.md
+- examples/basic/Gemfile
+- examples/basic/main.rb
+- examples/basic/message_listener.rb
+- examples/middleware/Gemfile
+- examples/middleware/main.rb
+- examples/middleware/meddling_message_middleware.rb
+- examples/middleware/message_listener.rb
+- examples/middleware_no_yield/Gemfile
+- examples/middleware_no_yield/main.rb
+- examples/middleware_no_yield/meddling_message_middleware.rb
+- examples/middleware_no_yield/message_listener.rb
+- examples/multi_listener/Gemfile
+- examples/multi_listener/main.rb
+- examples/multi_listener/message_listener.rb
+- examples/multi_listener/reaction_removed_listener.rb
 - lib/slack_bot-events.rb
 - lib/slack_bot/events.rb
 - lib/slack_bot/events/client.rb