octokit 4.2.0 → 9.2.0

data/lib/octokit/client/repository_invitations.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+    # Methods for the Repository Invitations API
+    #
+    # @see https://developer.github.com/v3/repos/invitations/
+    module RepositoryInvitations
+      # Invite a user to a repository
+      #
+      # Requires authenticated client
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param user [String] User GitHub username to add
+      # @return [Sawyer::Resource] The repository invitation
+      # @see https://developer.github.com/v3/repos/collaborators/#add-user-as-a-collaborator
+      def invite_user_to_repository(repo, user, options = {})
+        put "#{Repository.path repo}/collaborators/#{user}", options
+      end
+      alias invite_user_to_repo invite_user_to_repository
+
+      # List all invitations for a repository
+      #
+      # Requires authenticated client
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @return [Array<Sawyer::Resource>] A list of invitations
+      # @see https://developer.github.com/v3/repos/invitations/#list-invitations-for-a-repository
+      def repository_invitations(repo, options = {})
+        paginate "#{Repository.path repo}/invitations", options
+      end
+      alias repo_invitations repository_invitations
+
+      # Delete an invitation for a repository
+      #
+      # Requires authenticated client
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @param invitation_id [Integer] The id of the invitation
+      # @return [Boolean] True if the invitation was successfully deleted
+      # @see https://developer.github.com/v3/repos/invitations/#delete-a-repository-invitation
+      def delete_repository_invitation(repo, invitation_id, options = {})
+        boolean_from_response :delete, "#{Repository.path repo}/invitations/#{invitation_id}", options
+      end
+      alias delete_repo_invitation delete_repository_invitation
+
+      # Update an invitation for a repository
+      #
+      # Requires authenticated client
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @param invitation_id [Integer] The id of the invitation
+      # @return [Sawyer::Resource] The updated repository invitation
+      # @see https://developer.github.com/v3/repos/invitations/#update-a-repository-invitation
+      def update_repository_invitation(repo, invitation_id, options = {})
+        patch "#{Repository.path repo}/invitations/#{invitation_id}", options
+      end
+      alias update_repo_invitation update_repository_invitation
+
+      # List all repository invitations for the user
+      #
+      # Requires authenticated client
+      #
+      # @return [Array<Sawyer::Resource>] The users repository invitations
+      # @see https://developer.github.com/v3/repos/invitations/#list-a-users-repository-invitations
+      def user_repository_invitations(options = {})
+        paginate '/user/repository_invitations', options
+      end
+      alias user_repo_invitations user_repository_invitations
+
+      # Accept a repository invitation
+      #
+      # Requires authenticated client
+      #
+      # @param invitation_id [Integer] The id of the invitation
+      # @return [Boolean] True if the acceptance of the invitation was successful
+      # @see https://developer.github.com/v3/repos/invitations/#accept-a-repository-invitation
+      def accept_repository_invitation(invitation_id, options = {})
+        patch "/user/repository_invitations/#{invitation_id}", options
+      end
+      alias accept_repo_invitation accept_repository_invitation
+
+      # Decline a repository invitation
+      #
+      # Requires authenticated client
+      #
+      # @param invitation_id [Integer] The id of the invitation
+      # @return [Boolean] True if the acceptance of the invitation was successful
+      # @see https://developer.github.com/v3/repos/invitations/#decline-a-repository-invitation
+      def decline_repository_invitation(invitation_id, options = {})
+        boolean_from_response :delete, "/user/repository_invitations/#{invitation_id}", options
+      end
+      alias decline_invitation decline_repository_invitation
+    end
+  end
+end

data/lib/octokit/client/reviews.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+    # Methods for the Reviews API
+    #
+    # @see https://developer.github.com/v3/pulls/reviews/
+    module Reviews
+      # List reviews on a pull request
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @see https://developer.github.com/v3/pulls/reviews/#list-reviews-on-a-pull-request
+      #
+      # @example
+      #   @client.pull_request_reviews('octokit/octokit.rb', 2)
+      #
+      # @return [Array<Sawyer::Resource>] Array of Hashes representing the reviews
+      def pull_request_reviews(repo, number, options = {})
+        paginate "#{Repository.path repo}/pulls/#{number}/reviews", options
+      end
+
+      # Get a single review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @see https://developer.github.com/v3/pulls/reviews/#get-a-single-review
+      #
+      # @example
+      #   @client.pull_request_review('octokit/octokit.rb', 825, 6505518)
+      #
+      # @return [Sawyer::Resource] Hash representing the review
+      def pull_request_review(repo, number, review, options = {})
+        get "#{Repository.path repo}/pulls/#{number}/reviews/#{review}", options
+      end
+
+      # Delete a pending review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @see https://developer.github.com/v3/pulls/reviews/#delete-a-pending-review
+      #
+      # @example
+      #   @client.delete_pull_request_review('octokit/octokit.rb', 825, 6505518)
+      #
+      # @return [Sawyer::Resource] Hash representing the deleted review
+      def delete_pull_request_review(repo, number, review, options = {})
+        delete "#{Repository.path repo}/pulls/#{number}/reviews/#{review}", options
+      end
+
+      # Get comments for a single review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @see https://developer.github.com/v3/pulls/reviews/#get-comments-for-a-single-review
+      #
+      # @example
+      #   @client.pull_request_review_comments('octokit/octokit.rb', 825, 6505518)
+      #
+      # @return [Array<Sawyer::Resource>] Array of Hashes representing the review comments
+      def pull_request_review_comments(repo, number, review, options = {})
+        paginate "#{Repository.path repo}/pulls/#{number}/reviews/#{review}/comments", options
+      end
+
+      # Create a pull request review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param options [Hash] Method options
+      # @option options [String] :event The review action (event) to perform;
+      #   can be one of APPROVE, REQUEST_CHANGES, or COMMENT.
+      #   If left blank, the review is left PENDING.
+      # @option options [String] :body The body text of the pull request review
+      # @option options [Array<Hash>] :comments Comments part of the review
+      # @option comments [String] :path The path to the file being commented on
+      # @option comments [Integer] :position The position in the file to be commented on
+      # @option comments [String] :body Body of the comment
+      # @see https://developer.github.com/v3/pulls/reviews/#create-a-pull-request-review
+      #
+      # @example
+      #   comments = [
+      #     { path: '.travis.yml', position: 10, body: 'ruby-head is under development that is not stable.' },
+      #     { path: '.travis.yml', position: 32, body: 'ruby-head is also required in thervm section.' },
+      #   ]
+      #   options = { event: 'REQUEST_CHANGES', comments: comments }
+      #   @client.create_pull_request_review('octokit/octokit.rb', 844, options)
+      #
+      # @return [Sawyer::Resource>] Hash respresenting the review
+      def create_pull_request_review(repo, number, options = {})
+        post "#{Repository.path repo}/pulls/#{number}/reviews", options
+      end
+
+      # Submit a pull request review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @param event [String] The review action (event) to perform; can be one of
+      #                       APPROVE, REQUEST_CHANGES, or COMMENT.
+      # @param options [Hash] Method options
+      # @option options [String] :body The body text of the pull request review
+      # @see https://developer.github.com/v3/pulls/reviews/#submit-a-pull-request-review
+      #
+      # @example
+      #   @client.submit_pull_request_review('octokit/octokit.rb', 825, 6505518,
+      #                                      'APPROVE', body: 'LGTM!')
+      #
+      # @return [Sawyer::Resource] Hash respresenting the review
+      def submit_pull_request_review(repo, number, review, event, options = {})
+        options = options.merge(event: event)
+        post "#{Repository.path repo}/pulls/#{number}/reviews/#{review}/events", options
+      end
+
+      # Dismiss a pull request review
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @param message [String] The message for the pull request review dismissal
+      # @see https://developer.github.com/v3/pulls/reviews/#dismiss-a-pull-request-review
+      #
+      # @example
+      #   @client.dismiss_pull_request_review('octokit/octokit.rb', 825, 6505518, 'The message.')
+      #
+      # @return [Sawyer::Resource] Hash representing the dismissed review
+      def dismiss_pull_request_review(repo, number, review, message, options = {})
+        options = options.merge(message: message)
+        put "#{Repository.path repo}/pulls/#{number}/reviews/#{review}/dismissals", options
+      end
+
+      # List review requests
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @see https://developer.github.com/v3/pulls/review_requests/#list-review-requests
+      #
+      # @example
+      #   @client.pull_request_review_requests('octokit/octokit.rb', 2)
+      #
+      # @return [Array<Sawyer::Resource>] Array of Hashes representing the review requests
+      def pull_request_review_requests(repo, number, options = {})
+        paginate "#{Repository.path repo}/pulls/#{number}/requested_reviewers", options
+      end
+
+      # Create a review request
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param reviewers [Hash] :reviewers [Array<String>] An array of user logins
+      # @param options [Hash] :team_reviewers [Array<String>] An array of team slugs
+      # @see https://developer.github.com/v3/pulls/review_requests/#request-reviewers-for-a-pull-request
+      #
+      # @example
+      #   @client.request_pull_request_review('octokit/octokit.rb', 2, reviewers: ['soudy'])
+      #
+      # @return [Sawyer::Resource>] Hash respresenting the pull request
+      def request_pull_request_review(repo, number, reviewers = {}, options = {})
+        # TODO(5.0): remove deprecated behavior
+        if reviewers.is_a?(Array)
+          octokit_warn(
+            'Deprecated: Octokit::Client#request_pull_request_review ' \
+            "no longer takes a separate :reviewers argument.\n" \
+            'Please update your call to pass :reviewers and :team_reviewers as part of the options hash.'
+          )
+          options = options.merge(reviewers: reviewers)
+        else
+          options = options.merge(reviewers)
+        end
+
+        post "#{Repository.path repo}/pulls/#{number}/requested_reviewers", options
+      end
+
+      # Delete a review request
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The id of the pull request
+      # @param reviewers [Hash] :reviewers [Array] An array of user logins
+      # @param options [Hash] :team_reviewers [Array] An array of team slugs
+      #
+      # @see https://developer.github.com/v3/pulls/review_requests/#delete-a-review-request
+      #
+      # @example
+      #   options = {
+      #     "reviewers" => [ "octocat", "hubot", "other_user" ],
+      #     "team_reviewers" => [ "justice-league" ]
+      #   }
+      #   @client.delete_pull_request_review_request('octokit/octokit.rb', 2, options)
+      #
+      # @return [Sawyer::Resource>] Hash representing the pull request
+      def delete_pull_request_review_request(repo, id, reviewers = {}, options = {})
+        # TODO(5.0): remove deprecated behavior
+        if !reviewers.empty? && !options.empty?
+          octokit_warn(
+            'Deprecated: Octokit::Client#delete_pull_request_review_request ' \
+            "no longer takes a separate :reviewers argument.\n" \
+            'Please update your call to pass :reviewers and :team_reviewers as part of the options hash.'
+          )
+        end
+        # For backwards compatibility, this endpoint can be called with a separate reviewers hash.
+        # If not called with a separate hash, then 'reviewers' is, in fact, 'options'.
+        options = options.merge(reviewers)
+        delete "#{Repository.path repo}/pulls/#{id}/requested_reviewers", options
+      end
+
+      # Update a review request comment
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @param body [String] body text of the pull request review.
+      # @param options [Hash] Method options
+      # @see https://developer.github.com/v3/pulls/reviews/#update-a-pull-request-review
+      #
+      # @example
+      #   @client.update_pull_request_review('octokit/octokit.rb', 825, 6505518, 'This is close to perfect! Please address the suggested inline change. And add more about this.')
+      #
+      # @return [Sawyer::Resource] Hash representing the review comment
+      def update_pull_request_review(repo, number, review, body, options = {})
+        options[:body] = body
+        put "#{Repository.path repo}/pulls/#{number}/reviews/#{review}", options
+      end
+    end
+  end
+end

data/lib/octokit/client/say.rb

@@ -1,19 +1,18 @@
+# frozen_string_literal: true
+
 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
-
+      alias octocat say
     end
   end
 end

data/lib/octokit/client/search.rb

@@ -1,23 +1,37 @@
+# frozen_string_literal: true
+
 module Octokit
   class Client
-
     # Methods for the Search API
     #
     # @see https://developer.github.com/v3/search/
     module Search
-
       # Search code
       #
       # @param query [String] Search term and qualifiers
       # @param options [Hash] Sort and pagination options
       # @option options [String] :sort Sort field
       # @option options [String] :order Sort order (asc or desc)
-      # @option options [Fixnum] :page Page of paginated results
-      # @option options [Fixnum] :per_page Number of items per page
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
       # @return [Sawyer::Resource] Search results object
       # @see https://developer.github.com/v3/search/#search-code
       def search_code(query, options = {})
-        search "search/code", query, options
+        search 'search/code', query, options
+      end
+
+      # Search commits
+      #
+      # @param query [String] Search terms and qualifiers
+      # @param options [Hash] Sort and pagination options
+      # @option options [String] :sort Sort field
+      # @option options [String] :order Sort order (asc or desc)
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
+      # @return [Sawyer::Resource] Search results object
+      # @see https://developer.github.com/v3/search/#search-commits
+      def search_commits(query, options = {})
+        search 'search/commits', query, options
       end
 
       # Search issues
@@ -26,12 +40,13 @@ module Octokit
       # @param options [Hash] Sort and pagination options
       # @option options [String] :sort Sort field
       # @option options [String] :order Sort order (asc or desc)
-      # @option options [Fixnum] :page Page of paginated results
-      # @option options [Fixnum] :per_page Number of items per page
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
       # @return [Sawyer::Resource] Search results object
-      # @see https://developer.github.com/v3/search/#search-issues
+      # @see https://developer.github.com/v3/search/#search-issues-and-pull-requests
+      # @see https://docs.github.com/en/rest/search#limitations-on-query-length
       def search_issues(query, options = {})
-        search "search/issues", query, options
+        search 'search/issues', query, options
       end
 
       # Search repositories
@@ -40,14 +55,28 @@ module Octokit
       # @param options [Hash] Sort and pagination options
       # @option options [String] :sort Sort field
       # @option options [String] :order Sort order (asc or desc)
-      # @option options [Fixnum] :page Page of paginated results
-      # @option options [Fixnum] :per_page Number of items per page
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
       # @return [Sawyer::Resource] Search results object
       # @see https://developer.github.com/v3/search/#search-repositories
       def search_repositories(query, options = {})
-        search "search/repositories", query, options
+        search 'search/repositories', query, options
+      end
+      alias search_repos search_repositories
+
+      # Search topics
+      #
+      # @param query [String] Search term and qualifiers
+      # @param options [Hash] Sort and pagination options
+      # @option options [String] :sort Sort field
+      # @option options [String] :order Sort order (asc or desc)
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
+      # @return [Sawyer::Resource] Search results object
+      # @see https://developer.github.com/v3/search/#search-topics
+      def search_topics(query, options = {})
+        search 'search/topics', query, options
       end
-      alias :search_repos :search_repositories
 
       # Search users
       #
@@ -55,18 +84,18 @@ module Octokit
       # @param options [Hash] Sort and pagination options
       # @option options [String] :sort Sort field
       # @option options [String] :order Sort order (asc or desc)
-      # @option options [Fixnum] :page Page of paginated results
-      # @option options [Fixnum] :per_page Number of items per page
+      # @option options [Integer] :page Page of paginated results
+      # @option options [Integer] :per_page Number of items per page
       # @return [Sawyer::Resource] Search results object
       # @see https://developer.github.com/v3/search/#search-users
       def search_users(query, options = {})
-        search "search/users", query, options
+        search 'search/users', query, options
       end
 
       private
 
       def search(path, query, options = {})
-        opts = options.merge(:q => query)
+        opts = options.merge(q: query)
         paginate(path, opts) do |data, last_response|
           data.items.concat last_response.data.items
         end

data/lib/octokit/client/service_status.rb

@@ -1,37 +1,47 @@
+# frozen_string_literal: true
+
 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'
+      SUMMARY_ROOT    = 'https://www.githubstatus.com/api/v2/summary.json'
+      STATUS_ROOT     = 'https://www.githubstatus.com/api/v2/status.json'
+      COMPONENTS_ROOT = 'https://www.githubstatus.com/api/v2/components.json'
+
+      # Returns a summary with the current status and the last status messages.
+      #
+      # @return [<Sawyer::Resource>] GitHub status summary
+      # @see https://www.githubstatus.com/api#summory
+      def github_status_summary
+        get(SUMMARY_ROOT)
+      end
 
       # Returns the current system status
       #
       # @return [Sawyer::Resource] GitHub status
-      # @see https://status.github.com/api#api-current-status
+      # @see https://www.githubstatus.com/api#status
       def github_status
-        get(STATUS_ROOT).rels[:status].get.data
+        get(STATUS_ROOT)
       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
+      # @see https://www.githubstatus.com/api/#components
       def github_status_last_message
-        get(STATUS_ROOT).rels[:last_message].get.data
+        get(COMPONENTS_ROOT).components.first
       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
+      # @see https://www.githubstatus.com/api#components
       def github_status_messages
-        get(STATUS_ROOT).rels[:messages].get.data
+        get(COMPONENTS_ROOT).components
       end
     end
   end