Add Edit gist api (#240)

* Add Get a single gist and Get a specific revision of a gist APIs

- Add files property to domain.Gist

Signed-off-by: Aleksandr Vinokurov <aleksandr.vin@gmail.com>

* Update decoder for Gist, add decoder for GistFile

Signed-off-by: Aleksandr Vinokurov <aleksandr.vin@gmail.com>

* Add Edit a gist api

- Add EditGistFile, EditGistRequest to domain

Signed-off-by: Aleksandr Vinokurov <aleksandr.vin@gmail.com>

* Move EditGistFile encoder to Encoders object

Signed-off-by: Aleksandr Vinokurov <aleksandr.vin@gmail.com>

Author: aleksandr-vin

docs/src/main/tut/gist.md

@@ -9,6 +9,7 @@ Github4s supports the [Gist API](https://developer.github.com/v3/gists/). As a r
 with Github4s, you can:
 
 - [Create a gist](#create-a-gist)
+- [Get a single gist or specific revision of a gist](#get-a-gist)
 
 The following examples assume the following imports and token:
 
@@ -58,6 +59,70 @@ The `result` on the right is the created [Gist][gist-scala].
 
 See [the API doc](https://developer.github.com/v3/gists/#create-a-gist) for full reference.
 
+## Get a single gist or specific revision of a gist
+
+You can create a gist using `getGist`; it takes as arguments:
+
+- the gist id (obtained via [creation of a gist](#create-a-gist), for ex.).
+- optional sha of the gist revision.
+
+To get a single gist:
+
+```scala
+val singleGist = Github(accessToken).gists.getGist("aa5a315d61ae9438b18d")
+
+singleGist.exec[cats.Id, HttpResponse[String]]() match {
+  case Left(e) => println(s"Something went wrong: ${e.getMessage}")
+  case Right(r) => println(r.result)
+}
+```
+
+Similarly, to get a specific revision of a gist:
+
+```scala
+val sepcificRevisionGist = Github(accessToken).gists.getGist("aa5a315d61ae9438b18d", Some("4e481528046a016fc11d6e7d8d623b55ea11e372"))
+
+sepcificRevisionGist.exec[cats.Id, HttpResponse[String]]() match {
+  case Left(e) => println(s"Something went wrong: ${e.getMessage}")
+  case Right(r) => println(r.result)
+}
+```
+
+The `result` on the right is the requested [Gist][gist-scala].
+
+See [the API doc](https://developer.github.com/v3/gists/#get-a-single-gist) for full reference.
+
+## Edit a gist
+
+You can edit a gist using `editGist`; it takes as arguments:
+
+- the gist id (obtained via [creation of a gist](#create-a-gist), for ex.).
+- the gist description.
+- an association of file names and optional file contents where the contents are wrapped in
+[EditGistFile][gist-scala]s, if a new file name required, then it must be provided.
+
+To edit a gist (change description, update content of _token.scala_, rename _gh4s.scala_ and remove _token.class_ file):
+
+```scala
+import github4s.free.domain.EditGistFile
+val files = Map(
+  "token.scala" -> Some(EditGistFile("lazy val accessToken = sys.env.get(\"GITHUB4S_ACCESS_TOKEN\")")),
+  "gh4s.scala"  -> Some(EditGistFile("val gh = Github(accessToken)", Some("GH4s.scala"))),
+  "token.class"  -> None
+)
+
+val updatedGist = Github(accessToken).gists.editGist("aa5a315d61ae9438b18d", "Updated github4s entry point", files)
+
+updatedGist.exec[cats.Id, HttpResponse[String]]() match {
+  case Left(e) => println(s"Something went wrong: ${e.getMessage}")
+  case Right(r) => println(r.result)
+}
+```
+
+The `result` on the right is the updated [Gist][gist-scala].
+
+See [the API doc](https://developer.github.com/v3/gists/#edit-a-gist) for full reference.
+
 As you can see, a few features of the gist endpoint are missing. As a result, if you'd like to see a
 feature supported, feel free to create an issue and/or a pull request!
 

github4s/jvm/src/test/scala/github4s/unit/ApiSpec.scala

@@ -17,11 +17,10 @@
 package github4s.unit
 
 import github4s.api._
-import github4s.free.domain.{GistFile, Pagination}
+import github4s.free.domain.{EditGistFile, GistFile, Pagination}
 import github4s.utils.{DummyGithubUrls, MockGithubApiServer, TestUtilsJVM}
 import org.scalatest._
 import cats.implicits._
-
 import scalaj.http._
 import cats.Id
 import github4s.jvm.ImplicitsJVM
@@ -517,6 +516,47 @@ class ApiSpec
     }
   }
 
+  "Gists >> GetGist" should "return the single gist for a valid request" in {
+    val response =
+      gists.getGist(validGistId, sha = None, headerUserAgent, accessToken)
+    response should be('right)
+
+    response.toOption map { r ⇒
+      r.statusCode shouldBe okStatusCode
+    }
+  }
+
+  it should "return the specific revision of gist for a valid request" in {
+    val response =
+      gists.getGist(validGistId, sha = Some(validGistSha), headerUserAgent, accessToken)
+    response should be('right)
+
+    response.toOption map { r ⇒
+      r.statusCode shouldBe okStatusCode
+    }
+  }
+
+  "Gists >> EditGist" should "return the provided gist for a valid request" in {
+    val response =
+      gists.editGist(
+        validGistId,
+        validGistDescription,
+        Map(
+          validGistFilename → Some(EditGistFile(validGistFileContent)),
+          validGistOldFilename → Some(
+            EditGistFile(validGistFileContent, Some(validGistNewFilename))),
+          validGistDeletedFilename → None
+        ),
+        headerUserAgent,
+        accessToken
+      )
+    response should be('right)
+
+    response.toOption map { r ⇒
+      r.statusCode shouldBe okStatusCode
+    }
+  }
+
   "GitData >> GetReference" should "return the single reference" in {
     val response =
       gitData.reference(

github4s/jvm/src/test/scala/github4s/utils/MockGithubApiServer.scala

@@ -423,6 +423,78 @@ trait MockGithubApiServer extends MockServerService with FakeResponses with Test
         .withStatusCode(unauthorizedStatusCode)
         .withBody(unauthorizedResponse))
 
+  //Gists >> get a single gist
+
+  mockServer
+    .when(
+      request
+        .withMethod("GET")
+        .withPath(s"/gists/$validGistId")
+        .withHeader("Authorization", tokenHeader))
+    .respond(
+      response
+        .withStatusCode(okStatusCode)
+        .withBody(singleGistValidResponse))
+
+  mockServer
+    .when(
+      request
+        .withMethod("GET")
+        .withPath(s"/gists/$validGistId")
+        .withHeader(not("Authorization")))
+    .respond(
+      response
+        .withStatusCode(unauthorizedStatusCode)
+        .withBody(unauthorizedResponse))
+
+  //Gists >> get a specific revision of a gist
+
+  mockServer
+    .when(
+      request
+        .withMethod("GET")
+        .withPath(s"/gists/$validGistId/$validGistSha")
+        .withHeader("Authorization", tokenHeader))
+    .respond(
+      response
+        .withStatusCode(okStatusCode)
+        .withBody(specificRevisionOfGistValidResponse))
+
+  mockServer
+    .when(
+      request
+        .withMethod("GET")
+        .withPath(s"/gists/$validGistId/$validGistSha")
+        .withHeader(not("Authorization")))
+    .respond(
+      response
+        .withStatusCode(unauthorizedStatusCode)
+        .withBody(unauthorizedResponse))
+
+  //Gists >> edit a gist
+
+  mockServer
+    .when(
+      request
+        .withMethod("PATCH")
+        .withPath(s"/gists/$validGistId")
+        .withHeader("Authorization", tokenHeader))
+    .respond(
+      response
+        .withStatusCode(okStatusCode)
+        .withBody(editedGistValidResponse))
+
+  mockServer
+    .when(
+      request
+        .withMethod("PATCH")
+        .withPath(s"/gists/$validGistId")
+        .withHeader(not("Authorization")))
+    .respond(
+      response
+        .withStatusCode(unauthorizedStatusCode)
+        .withBody(unauthorizedResponse))
+
   // Git >> References
 
   mockServer

github4s/shared/src/main/scala/github4s/Decoders.scala

@@ -197,18 +197,29 @@ object Decoders {
       case PRRStateDismissed.value        => PRRStateDismissed
     }
 
+  implicit val decodeGistFile: Decoder[GistFile] = Decoder.instance { c ⇒
+    for {
+      content ← c.downField("content").as[String]
+    } yield
+      GistFile(
+        content = content
+      )
+  }
+
   implicit val decodeGist: Decoder[Gist] = Decoder.instance { c ⇒
     for {
       url         ← c.downField("url").as[String]
       id          ← c.downField("id").as[String]
       description ← c.downField("description").as[String]
       public      ← c.downField("public").as[Boolean]
+      files       ← c.downField("files").as[Map[String, GistFile]]
     } yield
       Gist(
         url = url,
         id = id,
         description = description,
-        public = public
+        public = public,
+        files = files
       )
   }
 

github4s/shared/src/main/scala/github4s/Encoders.scala

@@ -20,6 +20,7 @@ import github4s.free.domain._
 import io.circe._
 import io.circe.syntax._
 import io.circe.generic.auto._
+import io.circe.generic.semiauto.deriveEncoder
 
 object Encoders {
 
@@ -34,4 +35,9 @@ object Encoders {
   }
 
   implicit val encodePrrStatus: Encoder[PullRequestReviewState] = Encoder.encodeString.contramap(_.value)
+
+  implicit val encodeEditGistFile: Encoder[EditGistFile] = {
+    deriveEncoder[EditGistFile].mapJsonObject(_.filter(e =>
+      !(e._1.equals("filename") && e._2.isNull)))
+  }
 }

github4s/shared/src/main/scala/github4s/GithubAPIs.scala

@@ -175,6 +175,19 @@ class GHGists(accessToken: Option[String] = None)(implicit O: GistOps[GitHub4s])
       files: Map[String, GistFile]
   ): GHIO[GHResponse[Gist]] =
     O.newGist(description, public, files, accessToken)
+
+  def getGist(
+      gistId: String,
+      sha: Option[String] = None
+  ): GHIO[GHResponse[Gist]] =
+    O.getGist(gistId, sha, accessToken)
+
+  def editGist(
+      gistId: String,
+      description: String,
+      files: Map[String, Option[EditGistFile]]
+  ): GHIO[GHResponse[Gist]] =
+    O.editGist(gistId, description, files, accessToken)
 }
 
 class GHIssues(accessToken: Option[String] = None)(implicit O: IssueOps[GitHub4s]) {

github4s/shared/src/main/scala/github4s/api/Gists.scala

@@ -22,7 +22,7 @@ import io.circe.generic.auto._
 import io.circe.syntax._
 import github4s.GithubResponses.GHResponse
 import github4s.free.interpreters.Capture
-
+import github4s.Encoders.encodeEditGistFile
 import scala.language.higherKinds
 
 /** Factory to encapsulate calls related to Repositories operations  */
@@ -56,4 +56,45 @@ class Gists[C, M[_]](
       data = NewGistRequest(description, public, files).asJson.noSpaces
     )
 
+  /**
+   * Get a single gist or a specific revision of a gist
+   *
+   * @param gistId of the gist
+   * @param sha optional sha of a revision
+   * @param headers optional user headers to include in the request
+   * @param accessToken to identify the authenticated user
+   */
+  def getGist(
+      gistId: String,
+      sha: Option[String] = None,
+      headers: Map[String, String] = Map(),
+      accessToken: Option[String] = None): M[GHResponse[Gist]] =
+    httpClient.get[Gist](
+      accessToken,
+      ("gists" :: gistId :: sha.toList).mkString("/"),
+      headers
+    )
+
+  /**
+   * Edit a gist
+   *
+   * @param gistId of the gist
+   * @param files map describing the filenames of the Gist and its contents and/or new filenames
+   * @param headers optional user headers to include in the request
+   * @param accessToken to identify the authenticated user
+   */
+  def editGist(
+      gistId: String,
+      description: String,
+      files: Map[String, Option[EditGistFile]],
+      headers: Map[String, String] = Map(),
+      accessToken: Option[String] = None): M[GHResponse[Gist]] = {
+
+    httpClient.patch[Gist](
+      accessToken,
+      s"gists/$gistId",
+      headers,
+      data = EditGistRequest(description, files).asJson.noSpaces
+    )
+  }
 }