Add device management methods

src/MailosaurClient.php

@@ -8,6 +8,7 @@
 use Mailosaur\Operations\Messages;
 use Mailosaur\Operations\Servers;
 use Mailosaur\Operations\Usage;
+use Mailosaur\Operations\Devices;
 
 class MailosaurClient
 {
@@ -32,6 +33,9 @@ class MailosaurClient
     /** @var Operations\Usage */
     public $usage;
 
+    /** @var Operations\Devices */
+    public $devices;
+
 
     public function __construct($apiKey, $baseUri = 'https://mailosaur.com/')
     {
@@ -48,6 +52,8 @@ public function __construct($apiKey, $baseUri = 'https://mailosaur.com/')
         $this->analysis = new Analysis($this);
 
         $this->usage = new Usage($this);
+
+        $this->devices = new Devices($this);
     }
 
     /**
@@ -82,4 +88,4 @@ protected function setApiKey($apiKey)
         $this->apiKey = $apiKey;
     }
 
-}
+}

src/Models/Device.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Mailosaur\Models;
+
+
+class Device
+{
+    /** @var string Unique identifier for the device. */
+    public $id;
+
+    /** @var string A name used to identify the device. */
+    public $name;
+
+    public function __construct(\stdClass $data)
+    {
+        if (property_exists($data, 'id')) {
+            $this->id = $data->id;
+        }
+
+        if (property_exists($data, 'name')) {
+            $this->name = $data->name;
+        }
+    }
+}

src/Models/DeviceCreateOptions.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Mailosaur\Models;
+
+
+class DeviceCreateOptions
+{
+    /** @var string A name used to identify the device. */
+    public $name;
+
+    /** @var string The base32-encoded shared secret for this device. */
+    public $sharedSecret;
+
+    public function __construct()
+    {
+    }
+
+    /**
+     * @return array
+     */
+    public function __toArray()
+    {
+        $options = array(
+            'name'            => $this->name,
+            'sharedSecret'    => $this->sharedSecret
+        );
+
+        return $options;
+    }
+
+    public function toJsonString()
+    {
+        return json_encode($this->__toArray());
+    }
+}

src/Models/DeviceListResult.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Mailosaur\Models;
+
+
+class DeviceListResult
+{
+    /**
+     * @var Device[] The individual devices forming the result.
+     */
+    public $items = array();
+
+    public function __construct(\stdClass $data)
+    {
+        if (property_exists($data, 'items') && is_array($data->items)) {
+            foreach ($data->items as $item) {
+                $this->items[] = new Device($item);
+            }
+        }
+    }
+}

src/Models/OtpResult.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Mailosaur\Models;
+
+
+class OtpResult
+{
+    /** @var string The current one-time password. */
+    public $code;
+
+    /** @var \DateTime The expiry date/time of the current one-time password. */
+    public $expires;
+
+    public function __construct(\stdClass $data)
+    {
+        if (property_exists($data, 'code')) {
+            $this->code = $data->code;
+        }
+
+        if (property_exists($data, 'expires')) {
+            $this->expires = new \DateTime($data->expires);
+        }
+    }
+}

src/Operations/Devices.php

@@ -0,0 +1,108 @@
+<?php
+
+namespace Mailosaur\Operations;
+
+
+use Mailosaur\Models\Device;
+use Mailosaur\Models\DeviceCreateOptions;
+use Mailosaur\Models\DeviceListResult;
+use Mailosaur\Models\OtpResult;
+
+class Devices extends AOperation
+{
+
+    /**
+     * <strong>List all devices</strong>
+     *
+     * @return DeviceListResult
+     * @throws \Mailosaur\Models\MailosaurException
+     * @see     https://mailosaur.com/docs/api/#operation/Devices_List List all devices
+     * @example https://mailosaur.com/docs/api/#operation/Devices_List
+     */
+    public function all()
+    {
+        $response = $this->request('api/devices');
+
+        $response = json_decode($response);
+
+        return new DeviceListResult($response);
+    }
+
+    /**
+     * <strong>Create a device</strong>
+     * <p>Creates a new virtual security device and returns it.</p>
+     *
+     * @param $deviceCreateOptions
+     *
+     * @return \Mailosaur\Models\Device
+     * @throws \Mailosaur\Models\MailosaurException
+     * @see     https://mailosaur.com/docs/api/#operation/Devices_Create Create a device
+     * @example https://mailosaur.com/docs/api/#operation/Devices_Create
+     */
+    public function create(DeviceCreateOptions $deviceCreateOptions)
+    {
+        $payload = $deviceCreateOptions->toJsonString();
+
+        $response = $this->request(
+            'api/devices/',
+            array(
+                CURLOPT_CUSTOMREQUEST => 'POST',
+                CURLOPT_POSTFIELDS    => $payload,
+                CURLOPT_HTTPHEADER    => array('Content-Type:application/json', 'Content-Length: ' . strlen($payload))
+            )
+        );
+
+        $response = json_decode($response);
+
+        return new Device($response);
+    }
+
+    /**
+     * <strong>Retrieves the current one-time password for a saved device, or given base32-encoded shared secret.</strong>
+     *
+     * @param string $query Either the unique identifier of the device, or a base32-encoded shared secret.
+     *
+     * @return \Mailosaur\Models\OtpResult
+     * @throws \Mailosaur\Models\MailosaurException
+     * @see     https://mailosaur.com/docs/api/#operation/Devices_Otp Retrieve the current one-time password
+     * @example https://mailosaur.com/docs/api/#operation/Devices_Otp
+     */
+    public function otp($query)
+    {
+        if (str_contains($query, "-")) {
+            $response = $this->request('api/devices/' . urlencode($query) . '/otp');
+
+            $response = json_decode($response);
+
+            return new OtpResult($response);
+        }
+
+        $payload = json_encode(array('sharedSecret' => $query));
+        $response = $this->request(
+            'api/devices/otp',
+            array(
+                CURLOPT_CUSTOMREQUEST => 'POST',
+                CURLOPT_POSTFIELDS    => $payload,
+                CURLOPT_HTTPHEADER    => array('Content-Type:application/json', 'Content-Length: ' . strlen($payload))
+            )
+        );
+
+        $response = json_decode($response);
+
+        return new OtpResult($response);
+    }
+
+    /**
+     * <strong>Delete a device</strong>
+     *
+     * @param string $id The identifier of the device to be deleted.
+     *
+     * @throws \Mailosaur\Models\MailosaurException
+     * @see     https://mailosaur.com/docs/api/#operation/Devices_Delete Delete a device
+     * @example https://mailosaur.com/docs/api/#operation/Devices_Delete
+     */
+    public function delete($id)
+    {
+        $this->request('api/devices/' . urlencode($id), array(CURLOPT_CUSTOMREQUEST => 'DELETE'));
+    }
+}

tests/DevicesTests.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Mailosaur_Test;
+
+
+use Mailosaur\MailosaurClient;
+use Mailosaur\Models\DeviceCreateOptions;
+use Mailosaur\Models\MailosaurException;
+
+class DevicesTests extends \PHPUnit\Framework\TestCase
+{
+    /** @var \Mailosaur\MailosaurClient */
+    protected static $client;
+
+    public static function setUpBeforeClass(): void
+    {
+        $baseUrl = ($h = getenv('MAILOSAUR_BASE_URL')) ? $h : 'https://mailosaur.com/';
+        $apiKey  = getenv('MAILOSAUR_API_KEY');
+
+        if (empty($apiKey)) {
+            throw new \Exception('Missing necessary environment variables - refer to README.md');
+        }
+
+        self::$client = new MailosaurClient($apiKey, $baseUrl);
+    }
+
+    public function testCrud()
+    {
+        $deviceName = "My test";
+        $sharedSecret = "ONSWG4TFOQYTEMY=";
+
+        // Create a new device
+        $options       = new DeviceCreateOptions();
+        $options->name = $deviceName;
+        $options->sharedSecret = $sharedSecret;
+        $createdDevice = self::$client->devices->create($options);
+
+        $this->assertFalse(empty($createdDevice->id));
+        $this->assertEquals($deviceName, $createdDevice->name);
+
+        // Retrieve an otp via device ID
+        $otpResult = self::$client->devices->otp($createdDevice->id);
+        $this->assertEquals(6, strlen($otpResult->code));
+
+        $this->assertEquals(1, count(self::$client->devices->all()->items));
+        self::$client->devices->delete($createdDevice->id);
+        $this->assertEquals(0, count(self::$client->devices->all()->items));
+    }
+
+    public function testOtpViaSharedSecret()
+    {
+        $sharedSecret = "ONSWG4TFOQYTEMY=";
+
+        $otpResult = self::$client->devices->otp($sharedSecret);
+        $this->assertEquals(6, strlen($otpResult->code));
+    }
+}