cksh_commander 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 25be78fc47c94ddecfec773202ec0a40affdc40d
-  data.tar.gz: 1d2d18a2cd6856cffcdabdd9d531ba7cdcdec109
+  metadata.gz: f98c333fb1994d93150486351c05fac07578f1b1
+  data.tar.gz: 587802b3cb82c7bf0da152b10d5a25d836f7d1b1
 SHA512:
-  metadata.gz: f67bbb6ccf941cd8188fb83da89a89fe7eb55d81adcd90cf9de12b0a9fcd2ed0bcdfe90f91861b9b347dfea7b088c755675152147af55a30e9589338adc7d068
-  data.tar.gz: 1a0f136ad3651a93d6c469e576469c89e164a726dad83450200f84a4d77ae5791d9583cfa4cc3d6097fbf00a3c18e55e6dc7fcd0fe72fde1b73f2ed898c43a86
+  metadata.gz: 63295c5c7b1c4107287cac3ffb856f23828bef9be29fb45f6e4369091e192bad95bf15bb04efc4e5b38da4cce7be3ca1b3040d9b8f5ada096147da693f6c871a
+  data.tar.gz: bbbfe5fc04d24897757a5ef04f382e837fdbb631481d95d181621195f0cad60192471254b0318178c6677e701ed4073dd17ed11ae873eea453fad90fea43b34d

data/README.md

@@ -10,6 +10,15 @@ arguments. Check out the
 that comes bootstrapped with everything you need to process Slack slash
 commands using this gem.
 
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Getting Started](#getting-started)
+  - [Command API](#command-api)
+  - [Running a Command](#running-a-command)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+
 ### Installation
 
 You can install `cksh_commander` via RubyGems. In your Gemfile:
@@ -26,6 +35,8 @@ gem install cksh_commander
 
 ### Usage
 
+#### Getting Started
+
 Defining a custom command is easy. First, create a `commands/` directory and tell
 `CKSHCommander` where it can find your commands. Let's say we've created a `commands/`
 directory at the root of our project. Our configuration is as follows:
@@ -93,11 +104,28 @@ module Example
 end
 ```
 
-We set our slash command authentication token at the class level, and define
+#### Command API
+
+We `set` our slash command authentication token at the class level, and define
 methods for processing subcommands. Attachments (which take the form of a hash)
 can be added using `add_response_attachment(attachment)`. You can also set the
 response to `'in_channel'` at the method level with `respond_in_channel!`.
 
+We can access the Slack payload data via the `data` reader.
+
+```ruby
+data.token          #=> "gIkuvaNzQIHg97ATvDxqgjtO"
+data.team_id        #=> "T0001"
+data.team_domain    #=> "example"
+data.channel_id     #=> "C2147483705"
+data.channel_name   #=> "test"
+data.user_id        #=> "U2147483697"
+data.user_name      #=> "Randy"
+data.command        #=> "/test"
+data.text           #=> "subcommand"
+data.response_url   #=> "https://hooks.slack.com/commands/1234/5678"
+```
+
 Similar to [Thor](http://whatisthor.com/), we are able to document our
 command's API with the class-level `desc` method—as is shown in the example
 above. CKSHCommander provides a `help` subcommand out of the box, and this will
@@ -108,10 +136,47 @@ echo the documentation back to the Slack user.
 /example test1 [TEXT]  # Subcommand 1 description.
 /example [TEXT]        # Root command description.
 ```
+Use `authorize` to whitelist the user IDs of Slack users whom you've authorized
+to perform a subcommand. An unauthorized user who tries to use this subcommand will
+receive the response, "You are unauthorized to use this subcommand!" You can
+find the IDs of Slack users on your team using
+[Slack's REST API](https://slack.com/api/users.list?token=YOURTOKEN). Note that
+authorization is not performed unless `authorize` is used explicitly.
+
+```ruby
+...
+desc "privatecmd", "A private subcommand."
+def privatecmd
+  authorize(%w[U2147483697])
+  set_response_text("You are authorized!")
+end
+...
+```
+
+If you need to debug a subcommand and forward a caught exception to your Slack
+client, you can use `debug!` at the top of your subcommand's method body.
+Otherwise, exceptions at the subcommand level will result in the `set` error
+message text being returned to the client. Using `debug!` like this allows you
+to isolate testing to a single subcommand without disrupting all usage of the
+slash command.
+
+```ruby
+...
+set error_message: "Hm. Something went wrong!"
+
+def subcommand
+  debug!
+  undefined_method #=> NameError
+  set_response_text("Never evaluated...")
+end
+...
+```
+
+#### Running a Command
 
 To run a command, we use `CKSHCommander::Runner`. In the example below, we've
-created a simple Sinatra app to illustrate its usage with the standard Slack
-slash command payload.
+created a [simple Sinatra app](https://github.com/openarcllc/cksh_commander_api)
+to illustrate its usage with the standard Slack slash command payload.
 
 ```ruby
 # app.rb
@@ -133,6 +198,19 @@ post "/" do
 end
 ```
 
+### Examples
+
+Check out (and/or use) [example commands provided by the
+community](https://github.com/openarcllc/cksh_commander/tree/master/commands).
+Want to contribute a command? Great! Add your command to the `commands/` directory
+and open a pull request! The implementations below provide convenient reference
+points.
+
+| command | description |
+| --------|--------------- |
+| [jira](https://github.com/openarcllc/cksh_commander/tree/master/commands/jira)  | Display JIRA issue details in a Slack channel or message. |
+| [lunch](https://github.com/openarcllc/cksh_commander/tree/master/commands/lunch) | State or revoke your intention to attend the weekly lunch gathering. |
+
 ### 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.

data/commands/jira/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Dependencies
+gem "jira-ruby"

data/commands/jira/command.rb

@@ -0,0 +1,84 @@
+require "cksh_commander"
+require "jira"
+
+module Jira
+  class Command < CKSHCommander::Command
+    set token: "YOUR_SLASH_COMMAND_TOKEN"
+
+    # Location of your JIRA instance
+    JIRABASE = "http://localhost:3000/jira"
+
+    desc "issues [PROJECT] [STATUS]", "Get project issues."
+    def issues(project, status = nil)
+      content = "Issues for project: *#{project.upcase}*\n\n"
+
+      begin
+        issues = get_issues(project, status)
+        if issues.any?
+          issueoutput = issues.map { |i| issue_output(i) }.join("\n")
+          respond_in_channel!
+          add_response_attachment({
+            text: issueoutput, mrkdwn_in: ['text'], color: 'good'
+          })
+        else
+          content += "No matching issues found..."
+        end
+      rescue
+        content = "Encountered an error..."
+      end
+
+      set_response_text(content)
+    end
+
+    desc "[TICKET]", "Get ticket details."
+    def ___(issueid)
+      begin
+        issue = client.Issue.find(issueid)
+        set_response_text(issue_output(issue))
+        respond_in_channel!
+      rescue
+        set_response_text("Cannot find issue!")
+      end
+    end
+
+    private
+
+    def client
+      @jira ||= JIRA::Client.new({
+        username: "YOUR_JIRA_SYSTEM_USERNAME",
+        password: "YOUR_JIRA_SYSTEM_PASSWORD",
+        site: JIRABASE,
+        auth_type: :basic,
+        context_path: ""
+      })
+    end
+
+    def get_issues(project, status)
+      query = "project = #{project}"
+      query += " AND status = \"#{status}\"" if status
+
+      client.Issue.jql(query, {
+        startAt: 0,
+        max: 50,
+        fields: %w[summary assignee status issuetype key]
+      })
+    end
+
+    def issue_output(issue)
+      output = "<#{JIRABASE}/browse/#{issue.key}|*#{issue.key}*: #{issue.summary}>\n"
+      output += "*Type*: #{issue.fields['issuetype']['name']}\n"
+      output += "*Assignee*: #{assignee_output(issue.fields['assignee'])}\n"
+      output += "*Status*: #{issue.fields['status']['name']}\n"
+    end
+
+    def assignee_output(assignee)
+      return "Not Assigned" unless assignee
+      "#{assignee["displayName"]} " +
+        "<#{user_email(assignee["emailAddress"])}>"
+    end
+
+    def user_email(address)
+      "<mailto:#{address}|#{address}>"
+    end
+  end
+end

data/commands/lunch/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Dependencies
+gem "httparty"

data/commands/lunch/command.rb

@@ -0,0 +1,96 @@
+require "cksh_commander"
+require "httparty"
+require "json"
+
+module Lunch
+  class Command < CKSHCommander::Command
+    set token: "YOUR_SLASH_COMMAND_TOKEN"
+
+    # Keep track of who is in for lunch.
+    INFILE = File.expand_path("../in.txt", __FILE__)
+
+    desc "in", "State intention to attend the upcoming lunch."
+    def in
+      if user_in?
+        set_response_text("You're already in!")
+      else
+        add_user
+        set_response_text("You're in!")
+      end
+    end
+
+    desc "out", "Revoke intention to attend the upcoming lunch."
+    def out
+      if !user_in?
+        set_response_text("You aren't in, so you can't be out!")
+      else
+        remove_user
+        set_response_text("You're out!")
+      end
+    end
+
+    desc "who", "See who is attending the upcoming lunch."
+    def who
+      if attendees.any?
+        content = "Those IN for lunch: "
+        attendees.each_with_index do |a, i|
+          content += username_from_slug(a)
+          content += ", " unless i + 1 == attendees.count
+        end
+      else
+        content = "No one has committed to lunch..."
+      end
+
+      set_response_text(content)
+    end
+
+    # Allow a user to send out a lunch reminder; this requires Slack
+    # incoming webhook integration: https://api.slack.com/incoming-webhooks
+    def remind
+      payload = { text: "Lunch alert! Food in ~10 minutes!" }
+
+      attendees.each do |a|
+        # NOTE: Skip reminding the reminder...
+        # next if a == userslug
+
+        HTTParty.post(
+          "YOUR_SLACK_WEBHOOK_URL",
+          body: payload.merge({ channel: "@#{username_from_slug(a)}" }).to_json,
+          headers: { "Content-Type" => "application/json" })
+      end
+
+      set_response_text(attendees.any? ? "Reminders sent!" : "No one to remind...")
+    end
+
+    private
+
+    def attendees
+      File.read(INFILE).split("\n")
+    end
+
+    def add_user(slug = nil)
+      slug ||= userslug
+      File.open(INFILE, 'a') { |f| f.write("#{slug}\n") }
+    end
+
+    def remove_user
+      attending = attendees.dup
+      File.open(INFILE, 'w')
+      attending.dup.each do |a|
+        add_user(a) if userslug != a && a.size > 1
+      end
+    end
+
+    def user_in?
+      attendees.include?(userslug)
+    end
+
+    def userslug
+      "#{data.user_name}|#{data.user_id}"
+    end
+
+    def username_from_slug(slug)
+      slug.split('|')[0]
+    end
+  end
+end

data/lib/cksh_commander.rb

@@ -21,11 +21,7 @@ module CKSHCommander
     attr_accessor :commands_path
 
     def initialize
-      @commands_path = nil
-    end
-
-    def commands_path
-      @commands_path || "../commands"
+      @commands_path = "../commands"
     end
   end
 end

data/lib/cksh_commander/command.rb

@@ -3,7 +3,7 @@ require "cksh_commander/response"
 module CKSHCommander
   class Command
     class << self
-      attr_accessor :token
+      attr_accessor :token, :error_message
       attr_reader :docs
 
       def set(opts)
@@ -24,6 +24,8 @@ module CKSHCommander
 
     def initialize(data = nil)
       @data = data
+      @authorized = true
+      @debugging = false
       @response = Response.new
     end
 
@@ -83,10 +85,12 @@ module CKSHCommander
     end
 
     def set_response_text(text)
+      return unless @authorized
       @response.text = text
     end
 
     def add_response_attachment(attachment)
+      return unless @authorized
       unless attachment.is_a?(Hash)
         raise ArgumentError, "Attachment must be a Hash"
       end
@@ -95,9 +99,32 @@ module CKSHCommander
     end
 
     def respond_in_channel!
+      return unless @authorized
       @response.type = 'in_channel'
     end
 
+    # Authorize users to use a subcommand by
+    # whitelisting user IDs.
+    def authorize(ids)
+      @authorized = ids.any? { |id| @data.user_id == id }
+      unless @authorized
+        @response = Response.new("You are unauthorized to use this subcommand!")
+      end
+    end
+
+    def debug!
+      @debugging = true
+    end
+
+    def debugging?
+      @debugging
+    end
+
+    def error_message
+      self.class.error_message ||
+        "Something went awry..."
+    end
+
     private
 
     def subcommand_methods

data/lib/cksh_commander/runner.rb

@@ -12,8 +12,10 @@ module CKSHCommander
         cmd = Kernel.const_get(name).new(data)
 
         response = cmd.authenticated? ? cmd.run : Response.new("Invalid token!")
-      rescue NameError
-        response = Response.new("Command not found...")
+      rescue => e
+        text = cmd && cmd.debugging? ? e.message :
+          cmd ? cmd.error_message : "Command not found..."
+        response = Response.new(text)
       end
 
       response

data/lib/cksh_commander/version.rb

@@ -1,3 +1,3 @@
 module CKSHCommander
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cksh_commander
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Travis Loncar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-11 00:00:00.000000000 Z
+date: 2015-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -68,6 +68,11 @@ files:
 - bin/console
 - bin/setup
 - cksh_commander.gemspec
+- commands/jira/Gemfile
+- commands/jira/command.rb
+- commands/lunch/Gemfile
+- commands/lunch/command.rb
+- commands/lunch/in.txt
 - lib/cksh_commander.rb
 - lib/cksh_commander/command.rb
 - lib/cksh_commander/data.rb