Update to add job-status endpoint for list and single job-status obje…

…ct (#33)

* test: add job status tests like the events tests

This job status is based on a test account I'm using now, so it's as
good as the other tests.

  New file:   tests/JobStatusTest.php

* feat: job-status method accessors

Update the API list to have the job-status endpoints
Add the class file with the boilerplate Abs.php
Create the job-status endpoint class to get a list and a single id.

Link: https://docs.nylas.com/reference#job-statuses

  New file:   src/JobStatuses/Abs.php
  New file:   src/JobStatuses/JobStatus.php
  Modified:   src/Utilities/API.php

* feat: add job-statuses to client

  Modified:   src/Client.php

* feat: php7.3 doesn't support typed variables

Remove the typing of the variable.
Remove unused use Exception.

  Modified:   src/JobStatuses/JobStatus.php
  Modified:   tests/JobStatusTest.php

* feat: correct API endpoint list and usage

When sending to get the status list the api endpoint path is blank.
Corrected the array key to the right endpoint option.
Corrected the endpoint list to the right api path.

  Modified:   src/JobStatuses/JobStatus.php
  Modified:   src/Utilities/API.php

* test: correct test for response data

in the list test getJobStatusList wasn't defined.
in the specific id test, the result wasn't correct.
I had to use an id I had access to, and the result is a level down.

  Modified:   tests/JobStatusTest.php

* doc: add throw to list docblock

This exception appears to be thrown from the Sync::get().

  Modified:   src/JobStatuses/JobStatus.php

* doc: add job-statuses to README.md

  Modified:   README.md

* style: match API list style of plurals

Just want to match the pluralized style.

  Modified:   src/JobStatuses/JobStatus.php
  Modified:   src/Utilities/API.php

README.md

@@ -370,6 +370,12 @@ $nylas->Folders()->Folder()->xxx();
 $nylas->Labels()->Label()->xxx();
 ```
 
+### [Job-Statuses](https://docs.nylas.com/reference#job-statuses)
+
+```php
+$nylas->JobStatuses()->JobStatus()->xxx();
+```
+
 
 ### [Messages](https://docs.nylas.com/reference#messages)
 

src/Client.php

@@ -23,6 +23,7 @@
  * @method Messages\Abs       Messages()
  * @method Threads\Abs        Threads()
  * @method Webhooks\Abs       Webhooks()
+ * @method JobStatuses\Abs    JobStatuses()
  *
  * @author lanlin
  * @change 2021/03/18

src/JobStatuses/Abs.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Nylas\JobStatuses;
+
+use Nylas\Utilities\Abs as AbsTrait;
+
+/**
+ * ----------------------------------------------------------------------------------
+ * Nylas Abs
+ * ----------------------------------------------------------------------------------
+ *
+ * @method JobStatus JobStatus()
+ *
+ * @author lanlin
+ * @change 2020/04/26
+ */
+class Abs
+{
+    // ------------------------------------------------------------------------------
+
+    use AbsTrait;
+
+    // ------------------------------------------------------------------------------
+}

src/JobStatuses/JobStatus.php

@@ -0,0 +1,139 @@
+<?php
+
+namespace Nylas\JobStatuses;
+
+use Nylas\Utilities\API;
+use Nylas\Utilities\Helper;
+use Nylas\Utilities\Options;
+use Nylas\Utilities\Validator as V;
+
+/**
+ * ----------------------------------------------------------------------------------
+ * Nylas Job Statuses
+ * ----------------------------------------------------------------------------------
+ *
+ * @see https://docs.nylas.com/reference#job-statuses
+ *
+ * @author lanlin
+ * @update jeremygriffin
+ * @change 2021/05/05
+ */
+class JobStatus
+{
+    // ------------------------------------------------------------------------------
+
+    /**
+     * @var \Nylas\Utilities\Options
+     */
+    private $options;
+
+    // ------------------------------------------------------------------------------
+
+    /**
+     * JobStatus constructor.
+     *
+     * @param \Nylas\Utilities\Options $options
+     */
+    public function __construct(Options $options)
+    {
+        $this->options = $options;
+    }
+
+    // ------------------------------------------------------------------------------
+
+    /**
+     * get job-status list
+     *
+     * @param array $params
+     *
+     * @return array
+     * @throws \Exception
+     */
+    public function getJobStatusesList(array $params = []): array
+    {
+        $rules = $this->getBaseRules();
+
+        $rules[]     = V::keyOptional('view', V::in(['ids', 'count']));
+        $accessToken = $this->options->getAccessToken();
+
+        V::doValidate(V::keySet(...$rules), $params);
+        V::doValidate(V::stringType()->notEmpty(), $accessToken);
+
+        $header = ['Authorization' => $accessToken];
+
+        return $this->options
+            ->getSync()
+            ->setQuery($params)
+            ->setHeaderParams($header)
+            ->get(API::LIST['jobStatuses']);
+    }
+
+    // ------------------------------------------------------------------------------
+
+    /**
+     * get job-status
+     *
+     * @param array $params
+     *
+     * @return array
+     */
+    public function getJobStatus(array $params): array
+    {
+        $rules       = $this->getBaseRules();
+        $params      = Helper::arrayToMulti($params);
+        $accessToken = $this->options->getAccessToken();
+
+        $rules = V::simpleArray(V::keySet(
+            V::key('job_status_id', V::stringType()->notEmpty()),
+            ...$rules
+        ));
+
+        V::doValidate($rules, $params);
+        V::doValidate(V::stringType()->notEmpty(), $accessToken);
+
+        $queues = [];
+        $target = API::LIST['oneJobStatus'];
+        $header = ['Authorization' => $accessToken];
+
+        foreach ($params as $item)
+        {
+            $id = $item['job_status_id'];
+            unset($item['job_status_id']);
+
+            $request = $this->options
+                ->getAsync()
+                ->setPath($id)
+                ->setFormParams($item)
+                ->setHeaderParams($header);
+
+            $queues[] = static function () use ($request, $target)
+            {
+                return $request->get($target);
+            };
+        }
+
+        $jobID = Helper::generateArray($params, 'job_status_id');
+        $pools = $this->options->getAsync()->pool($queues, false);
+
+        return Helper::concatPoolInfos($jobID, $pools);
+    }
+
+    // ------------------------------------------------------------------------------
+
+    /**
+     * job-status base validate rules
+     *
+     * @return array
+     */
+    private function getBaseRules(): array
+    {
+        return
+        [
+            V::keyOptional('limit', V::intType()->min(1)),
+            V::keyOptional('offset', V::intType()->min(0)),
+            V::keyOptional('job_status_id', V::stringType()->notEmpty()),
+        ];
+    }
+
+    // ------------------------------------------------------------------------------
+}

src/Utilities/API.php

@@ -109,6 +109,11 @@ class API
         'deltaLongpoll'      => '/delta/longpoll',
         'deltaStreaming'     => '/delta/streaming',
         'deltaLatestCursor'  => '/delta/latest_cursor',
+
+        // JobStatuses
+        'jobStatuses'  => '/job-statuses',
+        'oneJobStatus' => '/job-statuses/%s',
+
     ];
 
     // ------------------------------------------------------------------------------

tests/JobStatusTest.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Nylas\Tests;
+
+/**
+ * ----------------------------------------------------------------------------------
+ * JobStatus Test
+ * ----------------------------------------------------------------------------------
+ *
+ * @update lanlin
+ * @change 2021/05/05
+ *
+ * @internal
+ */
+class JobStatusTest extends AbsCase
+{
+    // ------------------------------------------------------------------------------
+
+    public function testGetJobStatusList(): void
+    {
+        $data = $this->client->JobStatuses()->JobStatus()->getJobStatusesList();
+
+        $this->assertTrue(\count($data) > 0);
+    }
+
+    // ------------------------------------------------------------------------------
+
+    public function testGetJobStatus(): void
+    {
+        $params = ['job_status_id' => 'csihlkp7geos1org29z02xzm8'];
+
+        $data = $this->client->JobStatuses()->JobStatus()->getJobStatus($params);
+
+        //@NOTE: Format is [ '<job_status_id>' => [data in k => v]]
+        $this->assertArrayHasKey($params['job_status_id'], $data);
+        $this->assertArrayHasKey('job_status_id', $data[$params['job_status_id']]);
+    }
+
+    // ------------------------------------------------------------------------------
+}