Add repository collaborator; handle 204 response, accept permission (#106)

Author: timbonicus

src/main/java/com/spotify/github/v3/clients/RepositoryClient.java

@@ -187,9 +187,41 @@ public CompletableFuture<Boolean> isCollaborator(final String user) {
     return github.request(path).thenApply(response -> response.code() == NO_CONTENT);
   }
 
-  public CompletableFuture<RepositoryInvitation> addCollaborator(final String user) {
+  /**
+   * Add a collaborator to the repo.
+   *
+   * @param user       the GitHub username to add
+   * @param permission the permission level for the user; one of RepositoryPermission, or a custom
+   *                   role
+   * @return
+   */
+  public CompletableFuture<Optional<RepositoryInvitation>> addCollaborator(final String user,
+      final String permission) {
     final String path = String.format(REPOSITORY_COLLABORATOR, owner, repo, user);
-    return github.put(path, "", RepositoryInvitation.class);
+    final String data = github.json().toJsonUnchecked(Map.of("permission", permission));
+    return github
+        .put(path, data)
+        .thenApply(
+            response -> {
+              // Non-successful statuses result in an RequestNotOkException exception and this code
+              // not called.
+              if (response.code() == NO_CONTENT) {
+                /*
+                  GitHub returns a 204 when:
+                  - an existing collaborator is added as a collaborator
+                  - an organization member is added as an individual collaborator
+                  - an existing team member (whose team is also a repository collaborator) is
+                      added as a collaborator
+                 */
+                return Optional.empty();
+              }
+              final RepositoryInvitation invitation =
+                  github
+                      .json()
+                      .fromJsonUnchecked(
+                          GitHubClient.responseBodyUnchecked(response), RepositoryInvitation.class);
+              return Optional.of(invitation);
+            });
   }
 
   public CompletableFuture<Void> removeCollaborator(final String user) {

src/main/java/com/spotify/github/v3/repos/RepositoryPermission.java

@@ -0,0 +1,33 @@
+/*-
+ * -\-\-
+ * github-client
+ * --
+ * Copyright (C) 2016 - 2022 Spotify AB
+ * --
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * -/-/-
+ */
+
+package com.spotify.github.v3.repos;
+
+/** Helpful constants for Repository permissions. */
+public class RepositoryPermission {
+
+  public static final String PULL = "pull";
+  public static final String PUSH = "push";
+  public static final String ADMIN = "admin";
+  public static final String MAINTAIN = "maintain";
+  public static final String TRIAGE = "triage";
+
+  private RepositoryPermission() {}
+}

src/test/java/com/spotify/github/v3/clients/RepositoryClientTest.java

@@ -39,15 +39,13 @@
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
-import static org.mockito.ArgumentMatchers.contains;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Lists;
 import com.google.common.io.Resources;
-import com.google.common.net.HttpHeaders;
 import com.spotify.github.async.AsyncPage;
 import com.spotify.github.jackson.Json;
 import com.spotify.github.v3.comment.Comment;
@@ -61,6 +59,7 @@
 import com.spotify.github.v3.repos.FolderContent;
 import com.spotify.github.v3.repos.Repository;
 import com.spotify.github.v3.repos.RepositoryInvitation;
+import com.spotify.github.v3.repos.RepositoryPermission;
 import com.spotify.github.v3.repos.RepositoryTest;
 import com.spotify.github.v3.repos.Status;
 import com.spotify.github.v3.repos.requests.ImmutableAuthenticatedUserRepositoriesFilter;
@@ -165,12 +164,15 @@ public void isNotCollaborator() throws Exception {
 
   @Test
   public void addCollaborator() throws Exception {
-    final CompletableFuture<RepositoryInvitation> fixture =
-        completedFuture(json.fromJson(getFixture("repository_invitation.json"), RepositoryInvitation.class));
-    when(github.put("/repos/someowner/somerepo/collaborators/user", "", RepositoryInvitation.class)).thenReturn(fixture);
+    final Response response = createMockResponse("", getFixture("repository_invitation.json"));
+    when(github.put("/repos/someowner/somerepo/collaborators/user", "{\"permission\":\"pull\"}")).thenReturn(
+        completedFuture(response));
 
-    final RepositoryInvitation repoInvite = repoClient.addCollaborator("user").get();
+    final Optional<RepositoryInvitation> maybeInvite = repoClient.addCollaborator("user",
+        RepositoryPermission.PULL).get();
 
+    assertTrue(maybeInvite.isPresent());
+    final RepositoryInvitation repoInvite = maybeInvite.get();
     assertThat(repoInvite.id(), is(1));
     assertThat(repoInvite.nodeId(), is("MDEwOlJlcG9zaXRvcnkxMjk2MjY5"));
     assertThat(repoInvite.repository().id(), is(1296269));
@@ -180,6 +182,19 @@ public void addCollaborator() throws Exception {
     assertThat(repoInvite.permissions(), is("write"));
   }
 
+  @Test
+  public void addCollaboratorUserExists() throws Exception {
+    final Response response = mock(Response.class);
+    when(response.code()).thenReturn(204);
+    when(github.put("/repos/someowner/somerepo/collaborators/user", "{\"permission\":\"pull\"}")).thenReturn(
+        completedFuture(response));
+
+    final Optional<RepositoryInvitation> maybeInvite = repoClient.addCollaborator("user",
+        RepositoryPermission.PULL).get();
+
+    assertTrue(maybeInvite.isEmpty());
+  }
+
   @Test
   public void removeCollaborator() throws Exception {
     CompletableFuture<Response> response = completedFuture(mock(Response.class));