Merge pull request #9 from railsware/feature/permissions

Support general permission endpoints

CHANGELOG.md

@@ -1,3 +1,7 @@
+## [1.4.0] - 2023-04-20
+
+- Support general permission endpoints. Examples [here](examples/general/permissions.php)
+
 ## [1.3.0] - 2023-04-13
 
 - Support sandbox project endpoints. Examples [here](examples/sandbox/projects.php) 

examples/general/permissions.php

@@ -0,0 +1,62 @@
+<?php
+
+use Mailtrap\Config;
+use Mailtrap\DTO\Request\Permission\CreateOrUpdatePermission;
+use Mailtrap\DTO\Request\Permission\DestroyPermission;
+use Mailtrap\DTO\Request\Permission\PermissionInterface;
+use Mailtrap\DTO\Request\Permission\Permissions;
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapClient;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// your API token from here https://mailtrap.io/api-tokens
+$apiKey = getenv('MAILTRAP_API_KEY');
+$mailtrap = new MailtrapClient(new Config($apiKey));
+
+/**
+ * Get resources
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/permissions/resources
+ */
+try {
+    $accountId = getenv('MAILTRAP_ACCOUNT_ID');
+    $response = $mailtrap->general()->permissions()->getResources($accountId);
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+
+/**
+ * Manage user or token permissions
+ *
+ * If you send a combination of resource_type and resource_id that already exists, the permission is updated.
+ * If the combination doesn’t exist, the permission is created.
+ *
+ * PUT https://mailtrap.io/api/accounts/{account_id}/account_accesses/{account_access_id}/permissions/bulk
+ */
+try {
+    $accountId = getenv('MAILTRAP_ACCOUNT_ID');
+    $accountAccessId = getenv('MAILTRAP_ACCOUNT_ACCESS_ID');
+
+    // resource IDs
+    $projectResourceId = getenv('MAILTRAP_NEW_PROJECT_RESOURCE_ID');
+    $inboxResourceId = getenv('MAILTRAP_INBOX_RESOURCE_ID');
+    $destroyProjectResourceId = getenv('MAILTRAP_OLD_PROJECT_RESOURCE_ID');
+
+    $permissions = new Permissions(
+        new CreateOrUpdatePermission($projectResourceId, PermissionInterface::TYPE_PROJECT, 10), // viewer = 10
+        new CreateOrUpdatePermission($inboxResourceId, PermissionInterface::TYPE_INBOX, 100), // admin = 100
+        new DestroyPermission($destroyProjectResourceId, PermissionInterface::TYPE_PROJECT),
+    );
+
+    $response = $mailtrap->general()->permissions()->update($accountId, $accountAccessId, $permissions);
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}

src/Api/General/Permission.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\Api\General;
+
+use Mailtrap\Api\AbstractApi;
+use Mailtrap\DTO\Request\Permission\Permissions;
+use Mailtrap\Exception\RuntimeException;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Class Permission
+ */
+class Permission extends AbstractApi implements GeneralInterface
+{
+    /**
+     * Get all resources in your account (Inboxes, Projects, Domains, Billing and Account itself) to which the token has admin access.
+     *
+     * @param int $accountId
+     *
+     * @return ResponseInterface
+     */
+    public function getResources(int $accountId): ResponseInterface
+    {
+        return $this->handleResponse($this->httpGet(
+            sprintf('%s/api/accounts/%s/permissions/resources', $this->getHost(), $accountId)
+        ));
+    }
+
+    /**
+     * Manage user or token permissions.
+     * If you send a combination of resource_type and resource_id that already exists, the permission is updated.
+     * If the combination doesn’t exist, the permission is created.
+     *
+     * @param int         $accountId
+     * @param int         $accountAccessId
+     * @param Permissions $permissions
+     *
+     * @return ResponseInterface
+     */
+    public function update(int $accountId, int $accountAccessId, Permissions $permissions): ResponseInterface
+    {
+        return $this->handleResponse($this->httpPut(
+            sprintf('%s/api/accounts/%s/account_accesses/%s/permissions/bulk', $this->getHost(), $accountId, $accountAccessId),
+            [],
+            ['permissions' => $this->getPayload($permissions)]
+        ));
+    }
+
+    private function getPayload(Permissions $permissions): array
+    {
+        $payload = [];
+        foreach ($permissions->getAll() as $permission) {
+            $payload[] = $permission->toArray();
+        }
+
+        if (count($payload) === 0) {
+            throw new RuntimeException('At least one "permission" object should be added to manage user or token');
+        }
+
+        return $payload;
+    }
+}

src/DTO/Request/Permission/CreateOrUpdatePermission.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Permission;
+
+/**
+ * Class CreateOrUpdatePermission
+ */
+final class CreateOrUpdatePermission implements PermissionInterface
+{
+    private string $resourceId;
+    private string $resourceType;
+    private string $accessLevel;
+
+    /**
+     * @param string|int $resourceId
+     * @param string     $resourceType
+     * @param string|int $accessLevel
+     */
+    public function __construct($resourceId, string $resourceType, $accessLevel)
+    {
+        $this->resourceId = (string) $resourceId;
+        $this->resourceType = $resourceType;
+        $this->accessLevel = (string) $accessLevel;
+    }
+
+    public function getResourceId(): string
+    {
+        return $this->resourceId;
+    }
+
+    public function getResourceType(): string
+    {
+        return $this->resourceType;
+    }
+
+    public function getAccessLevel(): string
+    {
+        return $this->accessLevel;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'resource_id' => $this->getResourceId(),
+            'resource_type' => $this->getResourceType(),
+            'access_level' => $this->getAccessLevel(),
+        ];
+    }
+}

src/DTO/Request/Permission/DestroyPermission.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Permission;
+
+/**
+ * Class DestroyPermission
+ */
+final class DestroyPermission implements PermissionInterface
+{
+    private string $resourceId;
+    private string $resourceType;
+
+    /**
+     * @param string|int $resourceId
+     * @param string     $resourceType
+     */
+    public function __construct($resourceId, string $resourceType)
+    {
+        $this->resourceId = (string) $resourceId;
+        $this->resourceType = $resourceType;
+    }
+
+    public function getResourceId(): string
+    {
+        return $this->resourceId;
+    }
+
+    public function getResourceType(): string
+    {
+        return $this->resourceType;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'resource_id' => $this->getResourceId(),
+            'resource_type' => $this->getResourceType(),
+            '_destroy' => true,
+        ];
+    }
+}

src/DTO/Request/Permission/PermissionInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Mailtrap\DTO\Request\Permission;
+
+interface PermissionInterface
+{
+    public const TYPE_ACCOUNT = 'account';
+    public const TYPE_BILLING = 'billing';
+    public const TYPE_PROJECT = 'project';
+    public const TYPE_INBOX = 'inbox';
+    public const TYPE_MAILSEND_DOMAIN = 'mailsend_domain';
+
+    /**
+     * The ID of the resource
+     *
+     * @return string
+     */
+    public function getResourceId(): string;
+
+    /**
+     * Can be account, billing, project, inbox or mailsend_domain.
+     *
+     * @return string
+     */
+    public function getResourceType(): string;
+
+    /**
+     * Get permission as array
+     *
+     * @return array
+     */
+    public function toArray(): array;
+}

src/DTO/Request/Permission/Permissions.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Permission;
+
+/**
+ * Class Permissions
+ */
+final class Permissions
+{
+    /**
+     * @var PermissionInterface[]
+     */
+    private array $permissions = [];
+
+    public function __construct(PermissionInterface ...$permissions)
+    {
+        foreach ($permissions as $permission) {
+            $this->add($permission);
+        }
+    }
+
+    public function add(PermissionInterface $permission): Permissions
+    {
+        $this->permissions[] = $permission;
+
+        return $this;
+    }
+
+    /**
+     * @return PermissionInterface[]
+     */
+    public function getAll(): array
+    {
+        return $this->permissions;
+    }
+}

src/MailtrapGeneralClient.php

@@ -7,8 +7,9 @@
 use Mailtrap\Api;
 
 /**
- * @method Api\General\Account  accounts
- * @method Api\General\User     users
+ * @method Api\General\Account      accounts
+ * @method Api\General\User         users
+ * @method Api\General\Permission   permissions
  *
  * Class MailtrapGeneralClient
  */
@@ -17,5 +18,6 @@ final class MailtrapGeneralClient extends AbstractMailtrapClient
     public const API_MAPPING = [
         'accounts' => Api\General\Account::class,
         'users' => Api\General\User::class,
+        'permissions' => Api\General\Permission::class
     ];
 }