Rework GHResponse to incorporate useful data on unhappy path (#367)

Author: BenFradet

docs/docs/activity.md

@@ -49,9 +49,10 @@ You can subscribe or unsubscribe using `setThreadSub`; it takes as arguments:
 
 ```scala mdoc:compile-only
 val threadSub = Github[IO](accessToken).activities.setThreadSub(5, true, false)
-threadSub.unsafeRunSync match {
+val response = threadSub.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -73,9 +74,10 @@ To list the stargazers of 47deg/github4s:
 
 ```scala mdoc:compile-only
 val listStargazers = Github[IO](accessToken).activities.listStargazers("47deg", "github4s", true)
-listStargazers.unsafeRunSync match {
+val response = listStargazers.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -100,9 +102,10 @@ To list the starred repositories for user `rafaparadela`:
 
 ```scala mdoc:compile-only
 val listStarredRepositories = Github[IO](accessToken).activities.listStarredRepositories("rafaparadela", true)
-listStarredRepositories.unsafeRunSync match {
+val response = listStarredRepositories.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 

docs/docs/auth.md

@@ -50,9 +50,10 @@ val newAuth = Github[IO](None).auth.newAuth(
   "New access token",
   "e8e39175648c9db8c280",
   "1234567890")
-newAuth.unsafeRunSync match {
+val response = newAuth.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -76,9 +77,10 @@ val authorizeUrl = Github[IO](None).auth.authorizeUrl(
   "e8e39175648c9db8c280",
   "http://localhost:9000/_oauth-callback",
   List("public_repo"))
-authorizeUrl.unsafeRunSync match {
+val response = authorizeUrl.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -106,9 +108,10 @@ val getAccessToken = Github[IO](None).auth.getAccessToken(
   "code",
   "http://localhost:9000/_oauth-callback",
   "status")
-getAccessToken.unsafeRunSync match {
+val response = getAccessToken.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 

docs/docs/contributing.md

@@ -144,16 +144,17 @@ we'll be writing our tests in [GHReposSpec][repos-integ-spec]:
       .unsafeRunSync()
 
     testIsRight[List[Status]](response, { r =>
-      r.result.nonEmpty shouldBe true
-      r.statusCode shouldBe okStatusCode
+      r.nonEmpty shouldBe true
     })
+    response.statusCode shouldBe okStatusCode
   }
 
   it should "return an error when an invalid ref is provided" taggedAs Integration in {
     val response = Github[IO](accessToken).repos
       .listStatuses(validRepoOwner, validRepoName, invalidRef, headers = headerUserAgent)
       .unsafeRunSync()
     testIsLeft(response)
+    response.statusCode shouldBe notFoundStatusCode
   }
 ```
 
@@ -174,7 +175,7 @@ We're just checking that our API defined above hits the right endpoint, here:
 ```scala
 "Repos.listStatuses" should "call htppClient.get with the right parameters" in {
     val response: IO[GHResponse[List[Status]]] =
-      IO(Right(GHResult(List(status), okStatusCode, Map.empty)))
+      IO(GHResult(List(status).asRight, okStatusCode, Map.empty))
 
     implicit val httpClientMock = httpClientMockGet[List[Status]](
       url = s"repos/$validRepoOwner/$validRepoName/commits/$validRefSingle/statuses",
@@ -184,7 +185,6 @@ We're just checking that our API defined above hits the right endpoint, here:
     val repos = new RepositoriesInterpreter[IO]
 
     repos.listStatuses(validRepoOwner, validRepoName, validRefSingle, headerUserAgent)
-
   }
 ```
 
@@ -211,9 +211,10 @@ To list the statuses for a specific ref:
 val listStatuses =
   Github[IO](accessToken).repos.listStatuses("47deg", "github4s", "heads/master")
 
-listStatuses.unsafeRunSync match {
+val response = listStatuses.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 {triple backtick}
 
@@ -241,4 +242,4 @@ cd docs/target/site/ && jekyll serve
 [repos-integ-spec]: https://github.com/47deg/github4s/blob/master/github4s/src/test/scala/github4s/integration/GHReposSpec.scala
 [unit-pkg]: https://github.com/47deg/github4s/tree/master/github4s/src/test/scala/github4s/unit
 [repos-interpreter-spec]: https://github.com/47deg/github4s/blob/master/github4s/src/test/scala/github4s/unit/ReposSpec.scala
-[repos-md]: https://github.com/47deg/github4s/blob/master/docs/docs/repository.md
+[repos-md]: https://github.com/47deg/github4s/blob/master/docs/docs/repository.md

docs/docs/docs.md

@@ -29,13 +29,15 @@ Github4s uses [Tagless Final encoding](https://typelevel.org/blog/2017/12/27/opt
 
 Every Github4s API call returns an `F[GHResponse[A]]` where `F` has an instance of [cats.effect.ConcurrentEffect][cats-concurrent-effect].
 
-`GHResponse[A]` is, in turn, a type alias for `Either[GHException, GHResult[A]]`.
-
-`GHResult` contains the result `A` given by Github as well as the status code and headers of the
-response:
+`GHResponse[A]` contains the result `A` given by Github (or an error) as well as the status code and
+headers of the response:
 
 ```scala
-case class GHResult[A](result: A, statusCode: Int, headers: Map[String, String])
+final case class GHResponse[A](
+    result: Either[GHException, A],
+    statusCode: Int,
+    headers: Map[String, String]
+)
 ```
 
 As an introductory example, we can get a user with the following:
@@ -69,11 +71,11 @@ object ProgramIO {
   import cats.effect.IO.contextShift
   import scala.concurrent.ExecutionContext.Implicits.global
   import github4s.Github
-  
+
   implicit val IOContextShift = IO.contextShift(global)
 
   val u1 = Github[IO](accessToken).users.get("juanpedromoreno")
-  u1.unsafeRunSync
+  u1.unsafeRunSync()
 }
 ```
 
@@ -84,21 +86,19 @@ object ProgramTask {
     import monix.execution.Scheduler.Implicits.global
     import monix.eval.Task
     import github4s.Github
-    
+
     val u2 = Github[Task](accessToken).users.get("rafaparadela")
 }
 ```
 
-As mentioned above, `u2` should have an `Task[GHResponse[User]]`
+As mentioned above, `u2` should be a `Task[GHResponse[User]]`
 
 ```scala mdoc:silent:fail
 import github4s.GithubResponses.GHResult
 
-ProgramTask.u2.runAsync { result =>
-  result match {
-    case Right(GHResult(result, status@_, headers@_)) => doSomething
-    case Left(e) => doSomething
-  }
+ProgramTask.u2.runAsync() {
+  case GHResult(Right(result), status@_, headers@_) => doSomething
+  case GHResult(Left(error), status@_, headers@_) => doSomethingElse
 }
 
 ```
@@ -114,7 +114,7 @@ object ProgramId {
   import scala.concurrent.ExecutionContext.Implicits.global
   import github4s.Github
   import github4s.GithubIOSyntax._
-  
+
   implicit val IOContextShift = IO.contextShift(global)
 
   val u3 = Github[IO](accessToken).users.get("rafaparadela").toId
@@ -150,9 +150,9 @@ object ProgramEvalWithHeaders {
   import monix.execution.Scheduler.Implicits.global
   import monix.eval.Task
   import github4s.Github
-    
+
   val userHeaders = Map("user-agent" -> "github4s")
-  val u5 = Github[Task](accessToken).users.get("rafaparadela", userHeaders)  
+  val u5 = Github[Task](accessToken).users.get("rafaparadela", userHeaders)
 }
 ```
 

docs/docs/gist.md

@@ -46,10 +46,10 @@ val gistfiles = Map(
   "gh4s.scala"  -> GistFile("val gh = Github(accessToken)")
 )
 val newGist = Github[IO](accessToken).gists.newGist("Github4s entry point", public = true, gistfiles)
-
-newGist.unsafeRunSync match {
+val response = newGist.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -68,21 +68,21 @@ To get a single gist:
 
 ```scala mdoc:compile-only
 val singleGist = Github[IO](accessToken).gists.getGist("aa5a315d61ae9438b18d")
-
-singleGist.unsafeRunSync match {
+val response = singleGist.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
 Similarly, to get a specific revision of a gist:
 
 ```scala mdoc:compile-only
 val sepcificRevisionGist = Github[IO](accessToken).gists.getGist("aa5a315d61ae9438b18d", Some("4e481528046a016fc11d6e7d8d623b55ea11e372"))
-
-sepcificRevisionGist.unsafeRunSync match {
+val response = sepcificRevisionGist.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -110,10 +110,10 @@ val editfiles = Map(
 )
 
 val updatedGist = Github[IO](accessToken).gists.editGist("aa5a315d61ae9438b18d", "Updated github4s entry point", editfiles)
-
-updatedGist.unsafeRunSync match {
+val response = updatedGist.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 

docs/docs/git_data.md

@@ -58,10 +58,10 @@ You can get a reference using `getReference`, it takes as arguments:
 
 ```scala mdoc:compile-only
 val getReference = Github[IO](accessToken).gitData.getReference("47deg", "github4s", "heads/master")
-
-getReference.unsafeRunSync match {
+val response = getReference.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -88,10 +88,10 @@ val createReference = Github[IO](accessToken).gitData.createReference(
   "github4s",
   "refs/heads/master",
   "d3b048c1f500ee5450e5d7b3d1921ed3e7645891")
-
-createReference.unsafeRunSync match {
+val response = createReference.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -117,10 +117,10 @@ val updateReference = Github[IO](accessToken).gitData.updateReference(
   "heads/master",
   "d3b048c1f500ee5450e5d7b3d1921ed3e7645891",
   false)
-
-updateReference.unsafeRunSync match {
+val response = updateReference.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -139,10 +139,10 @@ You can get a commit using `getCommit`; it takes as arguments:
 
 ```scala mdoc:compile-only
 val getCommit = Github[IO](accessToken).gitData.getCommit("47deg", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891")
-
-getCommit.unsafeRunSync match {
+val response = getCommit.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -171,10 +171,10 @@ val createCommit = Github[IO](accessToken).gitData.createCommit(
   "827efc6d56897b048c772eb4087f854f46256132",
   List("d3b048c1f500ee5450e5d7b3d1921ed3e7645891"),
   None)
-
-createCommit.unsafeRunSync match {
+val response = createCommit.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -194,10 +194,10 @@ You can create a blob using `createBlob`; it takes as arguments:
 
 ```scala mdoc:compile-only
 val createBlob = Github[IO](accessToken).gitData.createBlob("47deg", "github4s", "New access token", Some("utf-8"))
-
-createBlob.unsafeRunSync match {
+val response = createBlob.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -225,10 +225,10 @@ You can get a tree using `getTree`; it takes as arguments:
 
 ```scala mdoc:compile-only
 val getTree = Github[IO](accessToken).gitData.getTree("47deg", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891", true)
-
-getTree.unsafeRunSync match {
+val response = getTree.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -270,10 +270,10 @@ val createTree = Github[IO](accessToken).gitData.createTree(
     "100644",
     "blob",
     "827efc6d56897b048c772eb4087f854f46256132")))
-
-createTree.unsafeRunSync match {
+val response = createTree.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```
 
@@ -305,10 +305,10 @@ val createTag = Github[IO](accessToken).gitData.createTag(
   "d3b048c1f500ee5450e5d7b3d1921ed3e7645891",
   "commit",
   Some(RefAuthor("2014-11-07T22:01:45Z", "rafaparadela", "developer@47deg.com")))
-
-createTag.unsafeRunSync match {
+val response = createTag.unsafeRunSync()
+response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
-  case Right(r) => println(r.result)
+  case Right(r) => println(r)
 }
 ```