octokit 1.25.0 → 2.0.0.pre

data/lib/octokit/client/say.rb

@@ -1,11 +1,17 @@
 module Octokit
   class Client
+
+    # Methods for the unpublished Octocat API
     module Say
 
+      # Return a nifty ASCII Octocat with GitHub wisdom
+      # or your own
+      # 
+      # @return [String]
       def say(text=nil)
         options = {}
         options[:s] = text if text
-        get "/octocat", options
+        get "octocat", options
       end
       alias :octocat :say
 

data/lib/octokit/client/service_status.rb

@@ -0,0 +1,39 @@
+module Octokit
+  class Client
+
+    # Methods for the GitHub Status API
+    #
+    # @see https://status.github.com/api
+    module ServiceStatus
+
+      # Root for status API
+      # @private
+      STATUS_ROOT = 'https://status.github.com/api.json'
+
+      # Returns the current system status
+      #
+      # @return [Sawyer::Resource] GitHub status
+      # @see https://status.github.com/api#api-current-status
+      def github_status
+        get(STATUS_ROOT).rels[:status].get.data
+      end
+
+      # Returns the last human communication, status, and timestamp.
+      #
+      # @return [Sawyer::Resource] GitHub status last message
+      # @see https://status.github.com/api#api-last-message
+      def github_status_last_message
+        get(STATUS_ROOT).rels[:last_message].get.data
+      end
+
+      # Returns the most recent human communications with status and timestamp.
+      #
+      # @return [Array<Sawyer::Resource>] GitHub status messages
+      # @see https://status.github.com/api#api-recent-messages
+      def github_status_messages
+        get(STATUS_ROOT).rels[:messages].get.data
+      end
+
+    end
+  end
+end

data/lib/octokit/client/stats.rb

@@ -1,11 +1,15 @@
 module Octokit
   class Client
+
+    # Methods for the Repository Statistics API
+    #
+    # @see http://developer.github.com/v3/repos/statistics/
     module Stats
 
     # Get contributors list with additions, deletions, and commit counts
     #
     # @param repo [String, Hash, Repository] A GitHub repository
-    # @return [Array<Hashie::Mash>] Array of contributor stats
+    # @return [Array<Sawyer::Resource>] Array of contributor stats
     # @see http://developer.github.com/v3/repos/statistics/#get-contributors-list-with-additions-deletions-and-commit-counts
     # @example Get contributor stats for octokit
     #   @client.contributors_stats('pengwynn/octokit')
@@ -17,7 +21,7 @@ module Octokit
     # Get the last year of commit activity data
     #
     # @param repo [String, Hash, Repository] A GitHub repository
-    # @return [Array<Hashie::Mash>] The last year of commit activity grouped by
+    # @return [Array<Sawyer::Resource>] The last year of commit activity grouped by
     #   week. The days array is a group of commits per day, starting on Sunday.
     # @see http://developer.github.com/v3/repos/statistics/#get-the-last-year-of-commit-activity-data
     # @example Get commit activity for octokit
@@ -29,7 +33,7 @@ module Octokit
     # Get the number of additions and deletions per week
     #
     # @param repo [String, Hash, Repository] A GitHub repository
-    # @return [Array<Hashie::Mash>] Weekly aggregate of the number of additions
+    # @return [Array<Sawyer::Resource>] Weekly aggregate of the number of additions
     #   and deletions pushed to a repository.
     # @see http://developer.github.com/v3/repos/statistics/#get-the-number-of-additions-and-deletions-per-week
     # @example Get code frequency stats for octokit
@@ -41,7 +45,7 @@ module Octokit
     # Get the weekly commit count for the repo owner and everyone else
     #
     # @param repo [String, Hash, Repository] A GitHub repository
-    # @return [Hashie::Mash] Total commit counts for the owner and total commit
+    # @return [Sawyer::Resource] Total commit counts for the owner and total commit
     #   counts in all. all is everyone combined, including the owner in the last
     #   52 weeks. If you’d like to get the commit counts for non-owners, you can
     #   subtract all from owner.
@@ -71,9 +75,11 @@ module Octokit
     #
     # @param repo [String, Hash, Repository] A GitHub repository
     # @param metric [String] The metrics you are looking for
-    # @return [Array<Hashie::Mash>] Magical unicorn stats
+    # @return [Array<Sawyer::Resource>] Magical unicorn stats
     def get_stats(repo, metric)
-      get("repos/#{Repository.new repo}/stats/#{metric}")
+      data = get("repos/#{Repository.new repo}/stats/#{metric}")
+
+      last_response.status == 202 ? nil : data
     end
 
     end

data/lib/octokit/client/statuses.rb

@@ -1,15 +1,19 @@
 module Octokit
   class Client
+
+    # Methods for the Commit Statuses API
+    #
+    # @see http://developer.github.com/v3/repos/statuses/
     module Statuses
 
       # List all statuses for a given commit
       #
       # @param repo [String, Repository, Hash] A GitHub repository
       # @param sha [String] The SHA1 for the commit
-      # @return [Array] A list of statuses
+      # @return [Array<Sawyer::Resource>] A list of statuses
       # @see http://developer.github.com/v3/repos/status
       def statuses(repo, sha, options={})
-        get("repos/#{Repository.new(repo)}/statuses/#{sha}", options)
+        get "repos/#{Repository.new(repo)}/statuses/#{sha}", options
       end
       alias :list_statuses :statuses
 
@@ -18,37 +22,12 @@ module Octokit
       # @param repo [String, Repository, Hash] A GitHub repository
       # @param sha [String] The SHA1 for the commit
       # @param state [String] The state: pending, success, failure, error
-      # @return [Hash] A status
+      # @return [Sawyer::Resource] A status
       # @see http://developer.github.com/v3/repos/status
       def create_status(repo, sha, state, options={})
         options.merge!(:state => state)
-        post("repos/#{Repository.new(repo)}/statuses/#{sha}", options)
-      end
-
-      # Returns the current system status
-      #
-      # @return [Hash] GitHub status
-      # @see https://status.github.com/api#api-current-status
-      def github_status
-        get('status.json', {:endpoint => Octokit.status_api_endpoint})
+        post "repos/#{Repository.new(repo)}/statuses/#{sha}", options
       end
-
-      # Returns the last human communication, status, and timestamp.
-      #
-      # @return [Hash] GitHub status last message
-      # @see https://status.github.com/api#api-last-message
-      def github_status_last_message
-        get('last-message.json', {:endpoint => Octokit.status_api_endpoint})
-      end
-
-      # Returns the most recent human communications with status and timestamp.
-      #
-      # @return [Array<Hash>] GitHub status messages
-      # @see https://status.github.com/api#api-recent-messages
-      def github_status_messages
-        get('messages.json', {:endpoint => Octokit.status_api_endpoint})
-      end
-
     end
   end
 end

data/lib/octokit/client/users.rb

@@ -1,17 +1,10 @@
 module Octokit
   class Client
-    module Users
 
-      # Search for user.
-      #
-      # @param search [String] User to search for.
-      # @return [Array<Hashie::Mash>] Array of hashes representing users.
-      # @see http://developer.github.com/v3/search/#search-users
-      # @example
-      #   Octokit.search_users('pengwynn')
-      def search_users(search, options={})
-        get("legacy/user/search/#{search}", options)['users']
-      end
+    # Methods for the Users API
+    #
+    # @see http://developer.github.com/v3/users/
+    module Users
 
       # List all GitHub users
       #
@@ -24,7 +17,7 @@ module Octokit
       #
       # @see http://developer.github.com/v3/users/#get-all-users
       #
-      # @return [Array] List of GitHub users.
+      # @return [Array<Sawyer::Resource>] List of GitHub users.
       def all_users(options={})
         get "users", options
       end
@@ -32,7 +25,7 @@ module Octokit
       # Get a single user
       #
       # @param user [String] A GitHub user name.
-      # @return [Hashie::Mash]
+      # @return [Sawyer::Resource]
       # @see http://developer.github.com/v3/users/#get-a-single-user
       # @example
       #   Octokit.user("sferik")
@@ -49,14 +42,17 @@ module Octokit
       # @param code [String] Authorization code generated by GitHub.
       # @param app_id [String] Client Id we received when our application was registered with GitHub.
       # @param app_secret [String] Client Secret we received when our application was registered with GitHub.
-      # @return [Hashie::Mash] Hash holding the access token.
-      # @see Octokit::Client
+      # @return [Sawyer::Resource] Hash holding the access token.
       # @see http://developer.github.com/v3/oauth/#web-application-flow
       # @example
       #   @client.access_token('aaaa', 'xxxx', 'yyyy', {:accept => 'application/json'})
-      def access_token(code, app_id, app_secret, options = {})
-        post("login/oauth/access_token", options.merge({:endpoint => Octokit.web_endpoint, :code => code,
-          :client_id => app_id, :client_secret => app_secret}))
+      def exchange_code_for_token(code, app_id = client_id, app_secret = client_secret, options = {})
+        options.merge!({
+          :code => code,
+          :client_id => app_id,
+          :client_secret => app_secret
+        })
+        post "#{web_endpoint}login/oauth/access_token", options
       end
 
       # Validate user username and password
@@ -81,42 +77,45 @@ module Octokit
       # @option options [String] :location
       # @option options [Boolean] :hireable
       # @option options [String] :bio
-      # @return [Hashie::Mash]
+      # @return [Sawyer::Resource]
       # @example
       #   Octokit.user(:name => "Erik Michaels-Ober", :email => "sferik@gmail.com", :company => "Code for America", :location => "San Francisco", :hireable => false)
       def update_user(options)
-        patch("user", options)
+        patch "user", options
       end
 
       # Get a user's followers.
       #
       # @param user [String] Username of the user whose list of followers you are getting.
-      # @return [Array<Hashie::Mash>] Array of hashes representing users followers.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing users followers.
       # @see http://developer.github.com/v3/users/followers/#list-followers-of-a-user
       # @example
       #   Octokit.followers('pengwynn')
       def followers(user=login, options={})
-        get("users/#{user}/followers", options)
+        get "users/#{user}/followers", options
       end
 
       # Get list of users a user is following.
       #
       # @param user [String] Username of the user who you are getting the list of the people they follow.
-      # @return [Array<Hashie::Mash>] Array of hashes representing users a user is following.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing users a user is following.
       # @see  http://developer.github.com/v3/users/followers/#list-users-following-another-user
       # @example
       #   Octokit.following('pengwynn')
       def following(user=login, options={})
-        get("users/#{user}/following", options)
+        get "users/#{user}/following", options
       end
 
       # Check if you are following a user.
       #
       # Requries an authenticated client.
       #
-      # @param user [String] Username of the user that you want to check if you are following.
-      # @return [Boolean] True if you are following the user, false otherwise.
-      # @see Octokit::Client
+      # @overload follows?(target)
+      #   @param target [String] Username of the user that you want to check if you are following.
+      # @overload follows?(user, target)
+      #   @param user [String] Username of first user
+      #   @param target [String] Username of the target user
+      # @return [Boolean] True following target user, false otherwise.
       # @see http://developer.github.com/v3/users/followers/#check-if-you-are-following-a-user
       # @example
       #   @client.follows?('pengwynn')
@@ -125,7 +124,7 @@ module Octokit
         user = args.first
         user ||= login
         return if user.nil?
-        boolean_from_response(:get, "user/following/#{target}")
+        boolean_from_response :get, "user/following/#{target}"
       end
 
       # Follow a user.
@@ -134,12 +133,11 @@ module Octokit
       #
       # @param user [String] Username of the user to follow.
       # @return [Boolean] True if follow was successful, false otherwise.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/users/followers/#follow-a-user
       # @example
       #   @client.follow('holman')
       def follow(user, options={})
-        boolean_from_response(:put, "user/following/#{user}", options)
+        boolean_from_response :put, "user/following/#{user}", options
       end
 
       # Unfollow a user.
@@ -148,12 +146,11 @@ module Octokit
       #
       # @param user [String] Username of the user to unfollow.
       # @return [Boolean] True if unfollow was successful, false otherwise.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/users/followers/#unfollow-a-user
       # @example
       #   @client.unfollow('holman')
       def unfollow(user, options={})
-        boolean_from_response(:delete, "user/following/#{user}", options)
+        boolean_from_response :delete, "user/following/#{user}", options
       end
 
       # Get list of repos starred by a user.
@@ -162,12 +159,13 @@ module Octokit
       # @param options [Hash] Optional options
       # @option options [String] :sort (created) Sort: <tt>created</tt> or <tt>updated</tt>.
       # @option options [String] :direction (desc) Direction: <tt>asc</tt> or <tt>desc</tt>.
-      # @return [Array<Hashie::Mash>] Array of hashes representing repositories starred by user.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing repositories starred by user.
       # @see http://developer.github.com/v3/repos/starring/#list-repositories-being-starred
       # @example
       #   Octokit.starred('pengwynn')
       def starred(user=login, options={})
-        get("users/#{user}/starred", options)
+        path = user_authenticated? ? "user/starred" : "users/#{user}/starred"
+        paginate path, options
       end
 
       # Check if you are starring a repo.
@@ -177,26 +175,11 @@ module Octokit
       # @param user [String] Username of repository owner.
       # @param repo [String] Name of the repository.
       # @return [Boolean] True if you are following the repo, false otherwise.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/repos/starring/#check-if-you-are-starring-a-repository
       # @example
       #   @client.starred?('pengwynn', 'octokit')
       def starred?(user, repo, options={})
-        boolean_from_response(:get, "user/starred/#{user}/#{repo}", options)
-      end
-
-      # Get list of repos watched by a user.
-      #
-      # Legacy, using github.beta media type. Use `Users#starred` instead.
-      #
-      # @param user [String] Username of the user to get the list of repositories they are watching.
-      # @return [Array<Hashie::Mash>] Array of hashes representing repositories watched by user.
-      # @see Users#starred
-      # @see http://developer.github.com/v3/repos/starring/#list-stargazers
-      # @example
-      #   Octokit.watched('pengwynn')
-      def watched(user=login, options={})
-        get("users/#{user}/watched", options)
+        boolean_from_response :get, "user/starred/#{user}/#{repo}", options
       end
 
       # Get a public key.
@@ -208,7 +191,7 @@ module Octokit
       # Requires authenticated client.
       #
       # @param key_id [Integer] Key to retreive.
-      # @return [Hashie::Mash] Hash representing the key.
+      # @return [Sawyer::Resource] Hash representing the key.
       # @see http://developer.github.com/v3/users/keys/#get-a-single-public-key
       # @example
       #   @client.key(1)
@@ -223,33 +206,32 @@ module Octokit
       #   public_key['key']
       #   # => "ssh-rsa AAA..."
       def key(key_id, options={})
-        get("user/keys/#{key_id}", options)
+        get "user/keys/#{key_id}", options
       end
 
       # Get list of public keys for user.
       #
       # Requires authenticated client.
       #
-      # @return [Array<Hashie::Mash>] Array of hashes representing public keys.
-      # @see Octokit::Client
+      # @return [Array<Sawyer::Resource>] Array of hashes representing public keys.
       # @see http://developer.github.com/v3/users/keys/#list-your-public-keys
       # @example
       #   @client.keys
       def keys(options={})
-        get("user/keys", options)
+        paginate "user/keys", options
       end
 
       # Get list of public keys for user.
       #
       # Requires authenticated client.
       #
-      # @return [Array<Hashie::Mash>] Array of hashes representing public keys.
-      # @see Octokit::Client
+      # @return [Array<Sawyer::Resource>] Array of hashes representing public keys.
       # @see http://developer.github.com/v3/users/keys/#list-public-keys-for-a-user
       # @example
       #   @client.user_keys('pengwynn'
       def user_keys(user, options={})
-        get("users/#{user}/keys", options)
+        # TODO: Roll this into .keys
+        paginate "users/#{user}/keys", options
       end
 
       # Add public key to user account.
@@ -258,13 +240,12 @@ module Octokit
       #
       # @param title [String] Title to give reference to the public key.
       # @param key [String] Public key.
-      # @return [Hashie::Mash] Hash representing the newly added public key.
-      # @see Octokit::Client
+      # @return [Sawyer::Resource] Hash representing the newly added public key.
       # @see http://developer.github.com/v3/users/keys/#create-a-public-key
       # @example
       #   @client.add_key('Personal projects key', 'ssh-rsa AAA...')
       def add_key(title, key, options={})
-        post("user/keys", options.merge({:title => title, :key => key}))
+        post "user/keys", options.merge({:title => title, :key => key})
       end
 
       # Update a public key
@@ -275,12 +256,12 @@ module Octokit
       # @param options [Hash] Hash containing attributes to update.
       # @option options [String] :title
       # @option options [String] :key
-      # @return [Hashie::Mash] Hash representing the updated public key.
+      # @return [Sawyer::Resource] Hash representing the updated public key.
       # @see http://developer.github.com/v3/users/keys/#update-a-public-key
       # @example
       #   @client.update_key(1, :title => 'new title', :key => "ssh-rsa BBB")
       def update_key(key_id, options={})
-        patch("/user/keys/#{key_id}", options)
+        patch "user/keys/#{key_id}", options
       end
 
       # Remove a public key from user account.
@@ -289,12 +270,11 @@ module Octokit
       #
       # @param id [String] Id of the public key to remove.
       # @return [Boolean] True if removal was successful, false otherwise.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/users/keys/#delete-a-public-key
       # @example
       #   @client.remove_key(1)
       def remove_key(id, options={})
-        boolean_from_response(:delete, "user/keys/#{id}", options)
+        boolean_from_response :delete, "user/keys/#{id}", options
       end
 
       # List email addresses for a user.
@@ -302,12 +282,11 @@ module Octokit
       # Requires authenticated client.
       #
       # @return [Array<String>] Array of email addresses.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/users/emails/#list-email-addresses-for-a-user
       # @example
       #   @client.emails
       def emails(options={})
-        get("user/emails", options)
+        paginate "user/emails", options
       end
 
       # Add email address to user.
@@ -316,12 +295,12 @@ module Octokit
       #
       # @param email [String] Email address to add to the user.
       # @return [Array<String>] Array of all email addresses of the user.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/users/emails/#add-email-addresses
       # @example
       #   @client.add_email('new_email@user.com')
       def add_email(email, options={})
-        post("user/emails", options.merge({:email => email}))
+        email = Array(email)
+        post "user/emails", email
       end
 
       # Remove email from user.
@@ -329,28 +308,30 @@ module Octokit
       # Requires authenticated client.
       #
       # @param email [String] Email address to remove.
-      # @return [Boolean] True if removal was successful, false otherwise.
-      # @see Octokit::Client
+      # @return [Array<String>] Array of all email addresses of the user.
       # @see http://developer.github.com/v3/users/emails/#delete-email-addresses
       # @example
       #   @client.remove_email('old_email@user.com')
-      def remove_email(email, options={})
-        boolean_from_response(:delete, "user/emails", options.merge({:email => email}))
+      def remove_email(email)
+        email = Array(email)
+        boolean_from_response :delete, "user/emails", email
       end
 
       # List repositories being watched by a user.
       #
       # @param user [String] User's GitHub username.
       #
-      # @return [Array<Hashie::Mashie>] Array of repositories.
+      # @return [Array<Sawyer::Resource>] Array of repositories.
       #
       # @see http://developer.github.com/v3/activity/watching/#list-repositories-being-watched
       #
       # @example
       #   @client.subscriptions("pengwynn")
       def subscriptions(user=login, options={})
-        get("users/#{user}/subscriptions", options)
+        path = user_authenticated? ? "user/subscriptions" : "users/#{user}/subscriptions"
+        paginate path, options
       end
+      alias :watched :subscriptions
 
     end
   end