slackbotsy 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f5a31ca60d39e4a589b2b8b2b317f16fa3eee69
-  data.tar.gz: 4e90621ec6c413ce68766cd17bb280d1739217ea
+  metadata.gz: 78670e10397ffcfd1cc98a51af115c7e5526e460
+  data.tar.gz: 53d8c0d28534b2068595e93cf9b9c64ddc669709
 SHA512:
-  metadata.gz: 22ec1b91901b433cd01fa242958be1c72db3cd811ec6340ac9f4e5efe23294f547acbe07539f993fc83750085be5f8e0f63d9f6a54f2e5d893a57060961f26f9
-  data.tar.gz: ff8d8701ad26335465be08863c6303a492dbb4b06e716871ea65ca91c91d948e395163bf951ea1c7d0fc5275b05d64e8a6f10771de2742af359d18a281d4b38c
+  metadata.gz: d3e36dc080d170fd71233061dd97ff52f9e14822a6aeedc96269ffacf98bcd0c55b79149abdfa81650a66ecaca1d80b2294251a5c13d4a874a94bce7dab29722
+  data.tar.gz: a2114b3535e6a0ca2e8146ed1828eec5e71a69de67325a3df42eadc1fdd6bd6513b1c5288368da87a494917d5a1168b6577b6a6004e85eb3bc3f92dfe291867a

data/README.md

@@ -36,14 +36,100 @@ gem install slackbotsy
 
 ## Setup
 
-botsy requires (at least) two webhooks setup in slack:
+botsy requires some or all of the following integrations setup in slack:
 
-* outgoing webhook: for slack to send messages out to botsy
+* outgoing webhook: for slack to send free-format messages out to botsy
+* slash command: for slack to send messages prefixed with a slash
+  command, for example `/botsy`
 * incoming webhook: for botsy `say` and `attach` methods to respond
 
 Set these up at https://your_team.slack.com/services/new and copy
 the webhook urls/tokens to botsy's config as below.
 
+## Sending messages to botsy
+
+You have three choices of how to send messages to botsy. It is fine to
+mix and match these to listen to different kinds of messages.
+
+### Global outgoing webhook
+
+This sends all messages from all channels to botsy, but requires a
+trigger word (e.g. `botsy`). This word must be included in
+`hear`-block regexes. The return from the hear block is posted
+publically to the sending channel. Alternatively, return `nil` and use
+`say` or `attach` to craft an asynchronous response.
+
+Requires you to set the `outgoing_token` config variable.
+
+### Per-channel outgoing webhooks
+
+These do not require any trigger word or magic prefix, but you must
+setup a webhook for every channel in which you want botsy to
+respond. This is useful to give your botsy a little personality, by
+seeming to respond to users' comments without being prompted.
+
+As with global webhooks, `hear` block returns public responses, or use
+`say` or `attach`.
+
+Add all required channel tokens to the `outgoing_token` array.
+
+### Slash commands
+
+You can define one or more slash integrations that send any messages
+with a slash trigger prefix (for example `/botsy`). A major advantage
+is that messages can be triggered from all channels, groups and
+private chats.
+
+The return value of the `hear`-block is sent as a _private_ response
+to the user (like communication from the built-in `slackbot`). This
+can be useful for requesting verbose bot information without spamming
+channels. To respond _publically_ from a `hear`-block, post direct to
+the channel using `say` or `attach`.
+
+The slash trigger itself is used in the `hear`-block regex match, so
+you may setup as many slash integrations as you like with different
+triggers, and respond appropriately.
+
+Add all slash integration tokens to config `slash_token`.
+
+## Sending messages to slack
+
+There are four methods of sending data to slack in response to
+matching a `hear` block. These may be mixed as necessary.
+
+### Simple response in return
+
+The return value from a `hear`-block is returned to slack in the http
+response to the sent message. This is a lightweight synchronous
+response to the same channel, and is sufficient for many needs.
+
+Note: responses to outgoing webhooks are posted publically, responses
+to slash commands are private to the requesting user (and appear to
+come from `slackbot`).
+
+### Post simple text to an incoming webhook with `say()`
+
+Asynchronous plain-text responses may be sent with the `say()` method
+from inside a `hear`-block. This is useful for multiple replies or to
+pass extra arguments, such as `channel`, to post response to a
+specific channel. It is also useful when botsy is expanded to be a
+general API for slack integration with third-party applications.
+
+Set the value of the `incoming_webhook` config variable to the URL
+given in your slack Incoming Webhook integration.
+
+### Post attachments to an incoming webook with `attach()`
+
+Works exactly like `say()`, except you may post JSON containing
+complex attachment information.
+
+### Upload data directly to slack using the API
+
+Call `post_message()` to get full access to the Slack Web API
+`/chat.postMessage` call. Argument is a hash containing the same
+variables described in the Web API docs. This allows uploading of text
+snippets and binary data.
+
 ## Example usage
 
 ```ruby
@@ -60,8 +146,8 @@ config = {
 
 bot = Slackbotsy::Bot.new(config) do
 
-  hear /echo\s+(.+)/ do |data, mdata|
-    "I heard #{data['user_name']} say '#{mdata[1]}' in #{data['channel_name']}"
+  hear /echo\s+(.+)/ do |mdata|
+    "I heard #{user_name} say '#{mdata[1]}' in #{channel_name}"
   end
 
   hear /flip out/i do

data/lib/slackbotsy/bot.rb

@@ -109,32 +109,45 @@ module Slackbotsy
     ## pass list of files containing hear statements, to be opened and evaled
     def eval_scripts(*files)
       files.flatten.each do |file|
-        self.instance_eval File.open(file).read
+        self.instance_eval(File.open(file).read)
       end
     end
 
     ## check message and run blocks for any matches
-    def handle_item(msg)
-      return nil unless @options['outgoing_token'].include? msg[:token] # ensure messages are for us from slack
+    def handle_outgoing_webhook(msg)
+      return nil unless @options['outgoing_token'].include?(msg[:token]) # ensure messages are for us from slack
       return nil if msg[:user_name] == 'slackbot'  # do not reply to self
       return nil unless msg[:text].is_a?(String) # skip empty messages
 
-      ## loop things to look for and collect immediate responses
-      ## rescue everything here so the bot keeps running even with a broken script
-      responses = @listeners.map do |hear|
-        if mdata = msg[:text].strip.match(hear.regex)
+      responses = get_responses(msg, msg[:text].strip)
+
+      if responses
+        { text: responses.compact.join("\n") }.to_json # webhook responses are json
+      end
+    end
+
+    def handle_slash_command(msg)
+      return nil unless @options['slash_token'].include?(msg[:token])
+
+      responses = get_responses(msg, "#{msg[:command]} #{msg[:text]}".strip)
+
+      if responses
+        responses.join("\n") # plain text responses
+      end
+    end
+
+    ## run on msg all hear blocks matching text
+    def get_responses(msg, text)
+      message = Slackbotsy::Message.new(self, msg)
+      @listeners.map do |listener|
+        text.match(listener.regex) do |mdata|
           begin
-            Slackbotsy::Message.new(self, msg).instance_exec(mdata, &hear.proc)
-          rescue => err
+            message.instance_exec(mdata, &listener.proc)
+          rescue => err # keep running even with a broken script, but report the error
             err
           end
         end
       end
-
-      ## format any replies for http response
-      if responses
-        { text: responses.compact.join("\n") }.to_json
-      end
     end
 
   end

data/lib/slackbotsy/version.rb

@@ -1,3 +1,3 @@
 module Slackbotsy
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slackbotsy
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Richard Lister
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-20 00:00:00.000000000 Z
+date: 2015-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.2.3
 signing_key: 
 specification_version: 4
 summary: Ruby bot for Slack chat.