slack-api-wrapper 0.0.5 → 0.0.6

data/lib/slack/web/chat.rb

@@ -1,29 +1,82 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the chat methods.
+    # Post chat messages to Slack.
     module Chat
+      # Endpoint scope
       SCOPE = "chat"
 
       # Deletes a message.
-      def chat_delete(params = {})
-        throw ArgumentError.new("Required arguments :ts missing") if params['ts'].nil?
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'ts'
+      #   Timestamp of the message to be deleted.
+      # @option params [channel] 'channel'
+      #   Channel containing the message to be deleted.
+      #
+      # @see https://api.slack.com/methods/chat.delete
+      def chat_delete(params={})
+        raise ArgumentError.new("Required arguments 'ts' missing") if params['ts'].nil?
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
         response = @session.do_get "#{SCOPE}.delete", params
         Slack::parse_response(response)
       end
 
       # Sends a message to a channel.
-      def chat_post_message(params = {})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :text missing") if params['text'].nil?
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [channel] 'channel'
+      #   Channel to send message to. Can be a public channel, private group or IM channel. Can be an encoded ID, or a name.
+      # @option params [Object] 'text'
+      #   Text of the message to send.
+      # @option params [Object] 'username'
+      #   Name of bot.
+      # @option params [Object] 'as_user'
+      #   Pass true to post the message as the authed user, instead of as a bot
+      # @option params [Object] 'parse'
+      #   Change how messages are treated.
+      # @option params [Object] 'link_names'
+      #   Find and link channel names and usernames.
+      # @option params [Object] 'attachments'
+      #   Structured message attachments.
+      # @option params [Object] 'unfurl_links'
+      #   Pass true to enable unfurling of primarily text-based content.
+      # @option params [Object] 'unfurl_media'
+      #   Pass false to disable unfurling of media content.
+      # @option params [Object] 'icon_url'
+      #   URL to an image to use as the icon for this message
+      # @option params [Object] 'icon_emoji'
+      #   emoji to use as the icon for this message. Overrides `icon_url`.
+      #
+      # @see https://api.slack.com/methods/chat.postMessage
+      def chat_post_message(params={})
+        raise ArgumentError.new("Required arguments 'channel' missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments 'text' missing") if params['text'].nil?
         response = @session.do_get "#{SCOPE}.postMessage", params
         Slack::parse_response(response)
       end
 
       # Updates a message.
-      def chat_update(params = {})
-        throw ArgumentError.new("Required arguments :ts missing") if params['ts'].nil?
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :text missing") if params['text'].nil?
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'ts'
+      #   Timestamp of the message to be updated.
+      # @option params [channel] 'channel'
+      #   Channel containing the message to be updated.
+      # @option params [Object] 'text'
+      #   New text for the message, using the default formatting rules.
+      #
+      # @see https://api.slack.com/methods/chat.update
+      def chat_update(params={})
+        raise 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 'text' missing") if params['text'].nil?
         response = @session.do_get "#{SCOPE}.update", params
         Slack::parse_response(response)
       end

data/lib/slack/web/emoji.rb

@@ -1,9 +1,19 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the emoji methods.
     module Emoji
+      # Endpoint scope
       SCOPE = "emoji"
 
       # Lists custom emoji for a team.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      #
+      # @see https://api.slack.com/methods/emoji.list
       def emoji_list(params={})
         response = @session.do_get "#{SCOPE}.list", params
         Slack::parse_response(response)

data/lib/slack/web/files.rb

@@ -1,29 +1,98 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the files methods.
+    # Get info on files uploaded to Slack, upload new files to Slack.
     module Files
+      # Endpoint scope
       SCOPE = "files"
 
-      #Deletes a file.
+      # Deletes a file.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [file] 'file'
+      #   ID of file to delete.
+      #
+      # @see https://api.slack.com/methods/files.delete
       def files_delete(params={})
-        throw ArgumentError.new("Required arguments :file missing") if params['file'].nil?
+        raise ArgumentError.new("Required arguments 'file' missing") if params['file'].nil?
         response = @session.do_get "#{SCOPE}.delete", params
         Slack::parse_response(response)
       end
 
       # Gets information about a team file.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [file] 'file'
+      #   File to fetch info for
+      # @option params [Object] 'count'
+      #   Number of items to return per page.
+      # @option params [Object] 'page'
+      #   Page number of results to return.
+      #
+      # @see https://api.slack.com/methods/files.info
       def files_info(params={})
-        throw ArgumentError.new("Required arguments :file missing") if params['file'].nil
+        raise ArgumentError.new("Required arguments :file missing") if params['file'].nil
         response = @session.do_get "#{SCOPE}.info", params
         Slack::parse_response(response)
       end
 
       # Lists & filters team files.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [user] 'user'
+      #   Filter files created by a single user.
+      # @option params [Object] 'ts_from'
+      #   Filter files created after this timestamp (inclusive).
+      # @option params [Object] 'ts_to'
+      #   Filter files created before this timestamp (inclusive).
+      # @option params [Object] 'types'
+      #   Filter files by type:
+      #
+      #   * `all` - All files
+      #   * `posts` - Posts
+      #   * `snippets` - Snippets
+      #   * `images` - Image files
+      #   * `gdocs` - Google docs
+      #   * `zips` - Zip files
+      #   * `pdfs` - PDF files
+      #
+      #   You can pass multiple values in the types argument, like `types=posts,snippets`.The default value is `all`, which does not filter the list.
+      # @option params [Object] 'count'
+      #   Number of items to return per page.
+      # @option params [Object] 'page'
+      #   Page number of results to return.
+      #
+      # @see https://api.slack.com/methods/files.list
       def files_list(params={})
         response = @session.do_get "#{SCOPE}.list", params
         Slack::parse_response(response)
       end
 
       # Uploads or creates a file.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'file'
+      #   File contents via `multipart/form-data`.
+      # @option params [Object] 'content'
+      #   File contents via a POST var.
+      # @option params [Object] 'filetype'
+      #   Slack-internal file type identifier.
+      # @option params [Object] 'filename'
+      #   Filename of file.
+      # @option options [Object] 'title'
+      #   Title of file.
+      # @option params [Object] 'initial_comment'
+      #   Initial comment to add to file.
+      # @option params [channel] 'channels'
+      #   Comma separated list of channels to share the file into.
+      # @see https://api.slack.com/methods/files.upload
       def files_upload(params={})
         response = @session.do_get "#{SCOPE}.upload", params
         Slack::parse_response(response)

data/lib/slack/web/groups.rb

@@ -1,114 +1,244 @@
+# Copyright (c) 2015 Gustavo Bazan
+# MIT License
+
 module Slack
   module Web
+    # Module for the groups methods.
+    # Get info on your team's private groups.
     module Groups
+      # Endpoint scope
       SCOPE = "groups"
 
       # Archives a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Private group to archive
+      #
+      # @see https://api.slack.com/methods/groups.archive
       def groups_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
 
       # Closes a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to close.
+      #
+      # @see https://api.slack.com/methods/groups.close
       def groups_close(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}.close", params
         Slack::parse_response(response)
       end
 
       # Creates a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'name'
+      #   Name of group to create
+      #
+      # @see https://api.slack.com/methods/groups.create
       def groups_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
 
       # Clones and archives a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'channel'
+      #  Group to clone and archive.
+      #
+      # @see https://api.slack.com/methods/groups.createChild
       def groups_create_child(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}.createChild", params
         Slack::parse_response(response)
       end
 
       # Fetches history of messages and events from a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group 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/groups.history
       def groups_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
 
       # Invites a user to a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Private group to invite user to.
+      # @option params [user] 'user'
+      #   User to invite.
+      #
+      # @see https://api.slack.com/methods/groups.invite
       def groups_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
 
       # Removes a user from a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to remove user from.
+      # @option params [user] 'user'
+      #   User to remove from group.
+      #
+      # @see https://api.slack.com/methods/groups.kick
       def groups_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 private group.
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to leave
+      #
+      # @see https://api.slack.com/methods/groups.leave
       def groups_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 private groups that the calling user has access to..
+      # Lists private groups that the calling user has access to.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [Object] 'exclude_archived'
+      #   Don't return archived groups.
+      #
+      # @see https://api.slack.com/methods/groups.list
       def groups_list(params={})
         response = @session.do_get "#{SCOPE}.list", params
         Slack::parse_response(response)
       end
 
       # Sets the read cursor in a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to set reading cursor in.
+      # @option params [timestamp] 'ts'
+      #   Timestamp of the most recently seen message.
+      #
+      # @see https://api.slack.com/methods/groups.mark
       def groups_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
 
       # Opens a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to open.
+      #
+      # @see https://api.slack.com/methods/groups.open
       def groups_open(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}.open", params
         Slack::parse_response(response)
       end
 
       # Renames a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to rename
+      # @option params [Object] 'name'
+      #   New name for group.
+      #
+      # @see https://api.slack.com/methods/groups.rename
       def groups_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 private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Private group to set the purpose of
+      # @option params [Object] 'purpose'
+      #   The new purpose
+      #
+      # @see https://api.slack.com/methods/groups.setPurpose
       def groups_set_purpose(params={})
-        throw ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
-        throw ArgumentError.new("Required arguments :pupose missing") if params['purpos'].nil?
+        raise ArgumentError.new("Required arguments :channel missing") if params['channel'].nil?
+        raise ArgumentError.new("Required arguments :pupose missing") if params['purpos'].nil?
         response = @session.do_get "#{SCOPE}.setPurpose", params
         Slack::parse_response(response)
       end
 
       # Sets the topic for a private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Private group to set the purpose of
+      # @option params [Object] 'topic'
+      #   The new topic
+      #
+      # @see https://api.slack.com/methods/groups.setTopic
       def groups_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 private group.
+      #
+      # @param [Hash] params
+      #   API call arguments
+      # @option params [group] 'channel'
+      #   Group to unarchive
+      # @raise [ArgumentError] if 'channel' is not present
+      # @see https://api.slack.com/methods/groups.unarchive
       def groups_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