Merge branch 'feature/final_auth_flow' into develop

docs/usage.md

@@ -2,11 +2,52 @@
 
 Using the API is designed to be as easy as possible for developers.
 
+## Human Connect popup
+See the [official documentation](https://docs.humanapi.co/docs/connect-setup) on how to set this up for new and
+existing users.
+
+## Finalising the auth flow
+Following the [official documentation](https://docs.humanapi.co/docs/connect-setup) on setting up your Connect
+popup will result in `POST` data being sent to your server endpoint defined in the Connect options of the previous step.
+Typically the `POST` data will look something like this:
+
+```php
+array(3) {
+ 'humanId' =>
+ string(24) "52867cbede3155565f000a0d"
+ 'clientId' =>
+ string(40) "2e9574ecd415c99346879d07689ec1c732c11036"
+ 'sessionToken' =>
+ string(32) "8836c122c0483eb193ac2dd121136931"
+}
+```
+To finalise the auth flow process we just need to create an auth object, and provide this `POST` data and your app's
+'client secret' key found in the settings of your application in the HumanAPI developer portal.
+
+```php
+use Choccybiccy\HumanApi\Auth;
+
+$clientSecret = "ee1551fb509598d0b656811633310889dc306aa3";
+
+$auth = new Auth($_POST, $clientSecret);
+$data = $auth->finish();
+```
+The response from the finish() method will look something like this:
+```php
+array(3) {
+ 'humanId' =>
+ string(24) "52867cbede3155565f000a0d"
+ 'accessToken' =>
+ string(40) "95891f14f4bcpa23261987effc7cfac7fedf7330"
+ 'publicToken' =>
+ string(32) "2767d6oea95f4c3db8e8f3d0a1238302"
+}
+```
+You should consider storing `humanId`, `accessToken` and `publicToken` against your user for later use.
+
 ## Human
 Creating an instance of human requires the user's access token.
 ```php
-<?php
-
 use Choccybiccy\HumanApi\Human;
 
 $human = new Human("myAccessToken");
@@ -17,8 +58,6 @@ From there you can begin querying the HumanAPI endpoints.
 ## Endpoints
 Creating an endpoint instance only requires the endpoint name.
 ```php
-<?php
-
 use Choccybiccy\HumanApi\Human;
 
 $human = new Human("myAccessToken");

src/HumanApi/Auth.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Choccybiccy\HumanApi;
+
+/**
+ * Class Auth
+ * @package Choccybiccy\HumanApi
+ */
+class Auth extends Api
+{
+
+ /**
+ * @var string
+ */
+ protected $apiUrl = "https://user.humanapi.co";
+
+ /**
+ * @var int
+ */
+ protected $apiVersion = 1;
+
+ /**
+ * @var array
+ */
+ protected $sessionTokenObject;
+
+ /**
+ * Constructor
+ *
+ * @see https://docs.humanapi.co/docs/connect-backend
+ *
+ * @param array $sessionTokenData
+ * @param string $clientSecret
+ */
+ public function __construct(array $sessionTokenData, $clientSecret)
+ {
+
+ $sessionTokenData['clientSecret'] = $clientSecret;
+ $this->sessionTokenData = $sessionTokenData;
+
+ parent::__construct();
+
+ }
+
+ /**
+ * Finish the auth flow and post to connect endpoint, and return response array
+ * containing accessToken and other data about the 'human' entity.
+ *
+ * @return array
+ */
+ public function finish()
+ {
+ $response = $this->post(
+ $this->buildUrlParts(array("tokens"), "connect"),
+ array(
+ "json" => $this->sessionTokenData,
+ )
+ );
+ return $response->json();
+ }
+}

tests/HumanApi/AuthTest.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Choccybiccy\HumanApi;
+
+use Choccybiccy\HumanApi\Traits\ReflectionMethods;
+
+/**
+ * Class AuthTest
+ * @package Choccybiccy\HumanApi
+ */
+class AuthTest extends \PHPUnit_Framework_TestCase
+{
+
+ use ReflectionMethods;
+
+ /**
+ * Get mock response
+ *
+ * @param int $statusCode Response status code
+ * @return \PHPUnit_Framework_MockObject_MockObject
+ */
+ protected function getMockResponse($statusCode = 204)
+ {
+ $response = $this->getMockBuilder('GuzzleHttp\Message\ResponseInterface')
+ ->disableOriginalConstructor()
+ ->setMethods(array("json", "getStatusCode", "getReasonPhrase"))
+ ->getMockForAbstractClass();
+ $response->expects($this->any())
+ ->method("json")
+ ->willReturn(array());
+ $response->expects($this->any())
+ ->method("getStatusCode")
+ ->willReturn($statusCode);
+ return $response;
+ }
+
+ /**
+ * Test auth
+ */
+ public function testAuth()
+ {
+
+ $sessionTokenData = array(
+ "humanId" => "exampleHumanId",
+ "clientId" => "exampleClientId",
+ "sessionToken" => "exampleSessionToken",
+ );
+
+ $clientSecret = "exampleClientSecret";
+
+ $auth = $this->getMockBuilder("Choccybiccy\\HumanApi\\Auth")
+ ->setConstructorArgs(array($sessionTokenData, $clientSecret))
+ ->setMethods(array("post"))
+ ->getMock();
+
+ $auth->expects($this->once())
+ ->method("post")
+ ->with(
+ $this->runProtectedMethod(
+ $auth,
+ "buildUrlParts",
+ array(array("tokens"), "connect")
+ ),
+ array(
+ "json" => array_merge($sessionTokenData, array("clientSecret" => $clientSecret)),
+ )
+ )
+ ->willReturn($this->getMockResponse());
+
+ $auth->finish();
+
+ }
+}