slack-api-wrapper 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82f17a8e6d648e7e04b4e738de427049fb6c80c0
-  data.tar.gz: 13a7ebe3f6728d354dad95647164ad92456b135c
+  metadata.gz: dedcbbf1b36c42b4eb57b2ed9ae32426db56e031
+  data.tar.gz: 72720e24918c02d42e573c659ca31e3540207a1f
 SHA512:
-  metadata.gz: 1130982045e83c3cd01862e94bd4b79b5535f0c6691de714407e4b5002b83a853b67a2044360059e938e63d64d72ef5fe31dcce5cd94b4e3b77b44e3830b22bc
-  data.tar.gz: d6d2f26145bae90283bb9c96dffbc9f22949362f1e49ddd6e3ade5e149290510fa26449ecb7cab48fbdf8b22537afc3eac8c3ecb452b39320a866b89ab710ac3
+  metadata.gz: 8795bfe54af70f6317508ece2bea2c0d2ea94feeb242f47ed6db8a82a95ac4563e2c3effeebc2d322d520d46455836c93fa4e4538154e773729969ee9596c9ef
+  data.tar.gz: b0de368f122442d43af86c55aab8372f7a73c20244a7b15348dce275623bfa566abd1ce5880a8fd08ad781fed113f625011e804dfa764201057d02c0aa1da3fc

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in slack.gemspec
+# Specify your gem's dependencies in slack-api-wrapper.gemspec
 gemspec

data/lib/slack-api-wrapper.rb

@@ -8,11 +8,26 @@ require_relative "slack/session"
 require_relative "slack/oauth2"
 require_relative "slack/client"
 
-module Slack # :nodoc:
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+#
+# The module that contains everything Slack-related:
+#
+# * {Slack::Client} is the class used to interact with the slack end points.
+# * {Slack::Error} is raised when Slack encounters an error.
+# * {Slack::Oauth2} handles oauth2 authentication.
+#
+module Slack
+  # Slack url
   WEB_SERVER = 'slack.com'
-  API_SERVER = "#{WEB_SERVER}/api"
+  # Slack api path
+  API_SERVER = 'slack.com/api'
 
+  # Removes nil params
   #
+  # @param [Hash] params
+  #   API call arguments
+  # @return [Hash]
   def self.clean_params(params)
     r = {}
     params.each do |k,v|
@@ -21,15 +36,24 @@ module Slack # :nodoc:
     r
   end
 
+  # Convert params to query string
   #
+  # @param [Hash] params
+  #   API call arguments
+  # @return [String]
   def self.make_query_string(params)
     clean_params(params).collect {|k,v|
       CGI.escape(k) + "=" + CGI.escape(v)
     }.join("&")
   end
 
-  #
-  def self.do_http(uri, request) # :nodoc:
+  # Handle http requests
+  # @param [URI::HTTPS] uri
+  #   API uri
+  # @param [Object] request
+  #   request object
+  # @return [Net::HTTPResponse]
+  def self.do_http(uri, request)
 
     http = Net::HTTP.new(uri.host, uri.port)
 
@@ -47,7 +71,11 @@ module Slack # :nodoc:
 
   # Parse response. You probably shouldn't be calling this directly.  This takes responses from the server
   # and parses them.  It also checks for errors and raises exceptions with the appropriate messages.
-  def self.parse_response(response, raw=false) # :nodoc:
+  # @param [Net::HTTPResponse] response
+  # @param [Boolean] raw if return raw data
+  # @raise [SlackError]
+  # @raise [SlackAuthError]
+  def self.parse_response(response, raw=false)
     if response.kind_of?(Net::HTTPServerError)
       raise SlackError.new("Slack Server Error: #{response} - #{response.body}", response)
     elsif response.kind_of?(Net::HTTPUnauthorized)
@@ -58,8 +86,10 @@ module Slack # :nodoc:
       rescue
         raise SlackError.new("Slack Server Error: body=#{response.body}", response)
       end
-      unless d['ok'] == true
-        raise SlackError.new(d['ok'], response)
+      if d['error']
+        raise SlackError.new(d['error'], response)
+      else
+        raise SlackError.new(response.body, response)
       end
     end
 
@@ -75,6 +105,9 @@ module Slack # :nodoc:
   # A string comparison function that is resistant to timing attacks.  If you're comparing a
   # string you got from the outside world with a string that is supposed to be a secret, use
   # this function to check equality.
+  # @param [String] a
+  # @param [String] b
+  # @return [Boolean] whether the strings are equal
   def self.safe_string_equals(a, b)
     if a.length != b.length
       false

data/lib/slack/client.rb

@@ -1,17 +1,19 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 require_relative 'session'
 require_relative 'web'
 
 module Slack
   # Use this class to make Slack API calls.  You'll need to obtain an OAuth 2 access token
-  # first; you can get one using SlackOAuth2Flow.
+  # first; you can get one using {Slack::OAuth2::Flow}.
   class Client
     include Web
 
-    # Args:
-    # * +oauth2_access_token+: Obtained via Slack::OAuth2::Flow.
+    # @param [String] oauth2_access_token user token
     def initialize(oauth2_access_token)
       if oauth2_access_token.is_a?(String)
-        @session = OAuth2Session.new(oauth2_access_token)
+        @session = Session.new(oauth2_access_token)
       else
         raise ArgumentError.new("oauth2_access_token doesn't have a valid type")
       end

data/lib/slack/error.rb

@@ -1,12 +1,23 @@
-# This is the usual error raised on any Slack related Errors
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
+  # This is the usual error raised on any Slack related Errors
+  # @!attribute http_response
+  #   @return [Object] server response
+  # @!attribute error
+  #   @return [String] the name of the error
   class Error < RuntimeError
+
     attr_accessor :http_response, :error
+
     def initialize(error, http_response=nil)
       @error = error
       @http_response = http_response
     end
 
+    # String representation
+    # @return [String]
     def to_s
       "#{error}"
     end

data/lib/slack/oauth2.rb

@@ -1,6 +1,10 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 require_relative 'oauth2/flow_base'
 require_relative 'oauth2/flow'
 module Slack
+  # Oauth2 authentication
   module Oauth2
   end
 end

data/lib/slack/oauth2/flow.rb

@@ -1,20 +1,27 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 require 'securerandom'
 
 require_relative 'flow_base'
 
 module Slack
-  module OAuth2
-    # The standard OAuth 2 authorization helper.  Use this if you're writing a web app.
+  module Oauth2
+    # The standard OAuth 2 authorization helper.
     class Flow < FlowBase
 
-      # * consumer_key: Your Slack API app's "app key"
-      # * consumer_secret: Your Slack API app's "app secret"
-      # * redirect_uri: The URI that the Slack server will redirect the user to after the user
+      # @param [String] consumer_key
+      #   Your Slack API app's "app key"
+      # @param [String] consumer_secret
+      #   Your Slack API app's "app secret"
+      # @param [String] redirect_uri
+      #   The URI that the Slack server will redirect the user to after the user
       #   finishes authorizing your app.  This URI  must be HTTPs-based and pre-registered with
       #   the Slack servers.
-      # * session: A hash that represents the current web app session (will be used to save the CSRF
-      #   token)
-      # * csrf_token_key: The key to use when storing the CSRF token in the session (for example,
+      # @param [Hash] session
+      #   represents the current web app session (will be used to save the CSRF token)
+      # @param [Object] csrf_token_key
+      #   The key to use when storing the CSRF token in the session (for example,
       #   :slack_auth_csrf_token)
       def initialize(consumer_key, consumer_secret, redirect_uri, scope, team, session, csrf_token_session_key)
         super(consumer_key, consumer_secret, scope, team)
@@ -36,10 +43,11 @@ module Slack
       # you provided to the constructor.  This CSRF token will be checked on finish() to prevent
       # request forgery.
       #
-      # * url_state: Any data you would like to keep in the URL through the authorization
+      # @param [String] url_state
+      #   Any data you would like to keep in the URL through the authorization
       #   process.  This exact value will be returned to you by finish().
       #
-      # Returns the URL to redirect the user to.
+      # @return Returns the URL to redirect the user to.
       def start(url_state=nil)
         unless url_state.nil? or url_state.is_a?(String)
           raise ArgumentError, "url_state must be a String"
@@ -57,21 +65,23 @@ module Slack
       # Call this after the user has visited the authorize URL (see: start()), approved your app,
       # and was redirected to your redirect URI.
       #
-      # * query_params: The query params on the GET request to your redirect URI.
+      # @param [Hash] query_params
+      #   The query params on the GET request to your redirect URI.
       #
-      # Returns a tuple of (access_token, scope, url_state).  access_token can be used to
-      # construct a SlackClient.  scpe is the Slack scope the user that jsut approved
-      # your app.  url_state is the value you originally passed in to start().
+      # @return Returns a tuple of (access_token, scope, url_state).  access_token can be used to
+      #   construct a SlackClient.  scpe is the Slack scope the user that jsut approved
+      #   your app.  url_state is the value you originally passed in to start().
       #
-      # Can throw BadRequestError, BadStateError, CsrfError, NotApprovedError,
-      # ProviderError.
+      # @raise [BadRequestError]
+      # @raise [BadStateError]
+      # @raise [CsrfError]
+      # @raise [NotApprovedError]
+      # @raise [ProviderError]
       def finish(query_params)
         csrf_token_from_session = @session[@csrf_token_session_key]
 
         # Check well-formedness of request.
 
-        # Check well-formedness of request.
-
         state = query_params['state']
         if state.nil?
           raise BadRequestError.new("Missing query parameter 'state'.")

data/lib/slack/oauth2/flow_base.rb

@@ -1,9 +1,12 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 require 'uri'
 
 module Slack
-  module OAuth2
+  module Oauth2
     # Base class for the OAuth 2 authorization helpers.
-    class FlowBase  # :nodoc:
+    class FlowBase
       def initialize(consumer_key, consumer_secret, scope, team)
         unless consumer_key.is_a?(String)
           raise ArgumentError, "consumer_key must be a String, got #{consumer_key.inspect}"

data/lib/slack/session.rb

@@ -1,7 +1,11 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
 
-  class OAuth2Session # :nodoc:
+  class Session # :nodoc:
 
+    # @param [String] oauth2_access_token user token
     def initialize(oauth2_access_token)
       unless oauth2_access_token.is_a?(String)
         raise "bad type for oauth2_access_token (expecting String)"
@@ -11,7 +15,7 @@ module Slack
 
     private
 
-    def build_url(path)
+    def build_url(path) # :nodoc:
       host = Slack::WEB_SERVER
       full_path = "/api/#{path}"
       URI::HTTPS.build({host: host, path: full_path})
@@ -38,7 +42,7 @@ module Slack
       do_http(uri, Net::HTTP::Get.new(uri.request_uri))
     end
 
-    def do_http_with_body(uri, request, body)
+    def do_http_with_body(uri, request, body) # :nodoc:
       if body != nil
         if body.is_a?(Hash)
           request.set_form_data(Slack::clean_params(body))

data/lib/slack/version.rb

@@ -1,3 +1,7 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
-  VERSION = '0.0.5'
+  # The current version of the wrapper.
+  VERSION = '0.0.6'
 end

data/lib/slack/web.rb

@@ -1,3 +1,7 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
+require_relative 'web/api'
 require_relative 'web/auth'
 require_relative 'web/channels'
 require_relative 'web/chat'
@@ -12,7 +16,9 @@ require_relative 'web/users'
 require_relative 'error'
 
 module Slack
+  # Web endpoints methods
   module Web
+    include Api
     include Auth
     include Channels
     include Chat
@@ -24,6 +30,5 @@ module Slack
     include Search
     include Team
     include Users
-
   end
 end

data/lib/slack/web/api.rb

@@ -1,9 +1,23 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
-    module Team
+    # Module for the api methods.
+    module Api
+      # Endpoint scope
       SCOPE = "api"
 
       # Checks API calling code.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'error'
+      #   Error response to return
+      # @option params [Object] 'foo'
+      #   example property to return
+      #
+      # @see https://api.slack.com/methods/api.test
       def api_test(params={})
         response = @session.do_get "#{SCOPE}.test", params
         Slack::parse_response(response)

data/lib/slack/web/auth.rb

@@ -1,8 +1,21 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the auth methods.
     module Auth
+      # Endpoint scope
+      SCOPE = "auth"
+
+      # Checks authentication & identity.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      #
+      # @see https://api.slack.com/methods/auth.test
       def auth_test(params={})
-        response = @session.do_get "auth.test", params
+        response = @session.do_get "#{SCOPE}.test", params
         Slack::parse_response(response)
       end
     end

data/lib/slack/web/channels.rb

@@ -1,107 +1,231 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the channels methods.
+    # Get info on your team's Slack channels, create or archive channels,
+    # invite users, set the topic and purpose, and mark a channel as read.
     module Channels
+      # Endpoint scope
       SCOPE = "channels"
 
       # Archives a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to archive
+      #
+      # @see https://api.slack.com/methods/channels.archive
       def channels_archive(params = {})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.archive", params
         Slack::parse_response(response)
       end
 
       # Creates a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'name'
+      #   Name of channel to create
+      #
+      # @see https://api.slack.com/methods/channels.create
       def channels_create(params = {})
-        throw ArgumentError.new("Required arguments :name missing") if params['name'].nil?
+        raise ArgumentError.new("Required arguments 'name' missing") if params['name'].nil?
         response = @session.do_get "#{SCOPE}.create", params
         Slack::parse_response(response)
       end
 
       # Fetches history of messages and events from a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to fetch history for.
+      # @option params [timestamp] 'latest'
+      #   Latest message timestamp to include in results.
+      # @option params [timestamp] 'oldest'
+      #   Oldest message timestamp to include in results.
+      # @option params [Object] 'inclusive'
+      #   Include messages with latest or oldest timestamp in results.
+      # @option params [Object] 'count'
+      #   Number of messages to return, between 1 and 1000.
+      #
+      # @see https://api.slack.com/methods/channels.history
       def channels_history(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.history", params
         Slack::parse_response(response)
       end
 
       # Gets information about a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to get info on
+      #
+      # @see https://api.slack.com/methods/channels.info
       def channels_info(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.info", params
         Slack::parse_response(response)
       end
 
       # Invites a user to a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to invite user to.
+      # @option params [user] 'user'
+      #   User to invite to channel.
+      #
+      # @see https://api.slack.com/methods/channels.invite
       def channels_invite(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :user missing") if params['user'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'user' missing") if params['user'].nil?
         response = @session.do_get "#{SCOPE}.invite", params
         Slack::parse_response(response)
       end
 
       # Joins a channel, creating it if needed.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'name'
+      #   Name of channel to join
+      #
+      # @see https://api.slack.com/methods/channels.join
       def channels_join(params={})
-        throw ArgumentError.new("Required arguments :name missing") if params['name'].nil?
+        raise ArgumentError.new("Required arguments 'name' missing") if params['name'].nil?
         response = @session.do_get "#{SCOPE}.join", params
         Slack::parse_response(response)
       end
 
       # Removes a user from a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to remove user from.
+      # @option params [user] 'user'
+      #   User to remove from channel.
+      #
+      # @see https://api.slack.com/methods/channels.kick
       def channels_kick(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :user missing") if params['user'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'user' missing") if params['user'].nil?
         response = @session.do_get "#{SCOPE}.kick", params
         Slack::parse_response(response)
       end
 
       # Leaves a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to leave
+      # @see https://api.slack.com/methods/channels.leave
       def channels_leave(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.leave", params
         Slack::parse_response(response)
       end
 
       # Lists all channels in a Slack team.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'exclude_archived'
+      #   Don't return archived channels.
+      #
+      # @see https://api.slack.com/methods/channels.list
       def channels_list(params={})
         response = @session.do_get "#{SCOPE}.list", params
         Slack::parse_response(response)
       end
 
       # Sets the read cursor in a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to set reading cursor in.
+      # @option params [timestamp] 'ts'
+      #   Timestamp of the most recently seen message.
+      #
+      # @see https://api.slack.com/methods/channels.mark
       def channels_mark(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :ts missing") if params['ts'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'ts' missing") if params['ts'].nil?
         response = @session.do_get "#{SCOPE}.mark", params
         Slack::parse_response(response)
       end
 
       # Renames a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to rename
+      # @option params [Object] 'name'
+      #   New name for channel.
+      #
+      # @see https://api.slack.com/methods/channels.rename
       def channels_rename(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :name missing") if params['name'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'name' missing") if params['name'].nil?
         response = @session.do_get "#{SCOPE}.rename", params
         Slack::parse_response(response)
       end
 
       # Sets the purpose for a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to set the purpose of
+      # @option params [Object] 'purpose'
+      #   The new purpose
+      #
+      # @see https://api.slack.com/methods/channels.setPurpose
       def channels_set_purpose(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :purpose missing") if params['purpose'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'purpose' missing") if params['purpose'].nil?
         response = @session.do_get "#{SCOPE}.setPurpose", params
         Slack::parse_response(response)
       end
 
       # Sets the topic for a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to set the topic of
+      # @option params [Object] 'topic'
+      #   The new topic
+      # @raise [ArgumentError] if 'channel' or 'topic' are not present
+      # @see https://api.slack.com/methods/channels.setTopic
       def channels_set_topic(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :topic missing") if params['topic'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'topic' missing") if params['topic'].nil?
         response = @session.do_get "#{SCOPE}.setTopic", params
         Slack::parse_response(response)
       end
 
       # Unarchives a channel.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to unarchive
+      # @raise [ArgumentError] if 'channel' is not present
+      # @see https://api.slack.com/methods/channels.unarchive
       def channels_unarchive(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.unarchive", params
         Slack::parse_response(response)
       end