Add email folders endpoints

src/MsGraph.php

@@ -9,7 +9,7 @@
 use Dcblogdev\MsGraph\Events\NewMicrosoft365SignInEvent;
 use Dcblogdev\MsGraph\Models\MsGraphToken;
 use Dcblogdev\MsGraph\Resources\Contacts;
-use Dcblogdev\MsGraph\Resources\Emails;
+use Dcblogdev\MsGraph\Resources\Emails\Emails;
 use Dcblogdev\MsGraph\Resources\Files;
 use Dcblogdev\MsGraph\Resources\Sites;
 use Dcblogdev\MsGraph\Resources\Tasks\TaskLists;
@@ -340,7 +340,8 @@ protected function guzzle(string $type, string $request, array $data = [], array
             return $responseObject;
 
         } catch (ClientException $e) {
-            return json_decode(($e->getResponse()->getBody()->getContents()));
+            throw new Exception($e->getMessage());
+            //return json_decode(($e->getResponse()->getBody()->getContents()));
         } catch (Exception $e) {
             throw new Exception($e->getMessage());
         }

src/Resources/Emails.php → src/Resources/Emails/Emails.php

@@ -1,12 +1,17 @@
 <?php
 
-namespace Dcblogdev\MsGraph\Resources;
+namespace Dcblogdev\MsGraph\Resources\Emails;
 
 use Dcblogdev\MsGraph\Facades\MsGraph;
 use Exception;
 
 class Emails extends MsGraph
 {
+    public function folders(): Folders
+    {
+        return new Folders;
+    }
+
     private string $top = '';
 
     private string $skip = '';

src/Resources/Emails/Folders.php

@@ -0,0 +1,117 @@
+<?php
+
+namespace Dcblogdev\MsGraph\Resources\Emails;
+
+use Dcblogdev\MsGraph\Facades\MsGraph;
+use Dcblogdev\MsGraph\Validators\EmailFolderCopyValidator;
+use Dcblogdev\MsGraph\Validators\EmailFolderStoreValidator;
+use Dcblogdev\MsGraph\Validators\EmailFolderUpdateValidator;
+use Dcblogdev\MsGraph\Validators\GraphQueryValidator;
+
+class Folders extends MsGraph
+{
+    public function get(array $params = [], bool $sort = false, array $priorityOrder = []): array
+    {
+        GraphQueryValidator::validate($params);
+
+        $queryString = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
+        $url = 'me/mailFolders'.(! empty($queryString) ? "?$queryString" : '');
+
+        $folders = MsGraph::get($url);
+
+        if (! isset($folders['value'])) {
+            return $folders;
+        }
+
+        $allFolders = $this->fetchSubfolders($folders['value']);
+
+        if ($sort) {
+            $allFolders = $this->sortFolders($allFolders, $priorityOrder);
+        }
+
+        return array_merge($folders, ['value' => $allFolders]);
+    }
+
+    public function find(string $id): array
+    {
+        return MsGraph::get('me/mailFolders/'.$id);
+    }
+
+    public function store(array $data): array
+    {
+        EmailFolderStoreValidator::validate($data);
+
+        return MsGraph::post('me/mailFolders', $data);
+    }
+
+    public function update(array $data, string $id): array
+    {
+        EmailFolderUpdateValidator::validate($data);
+
+        return MsGraph::patch('me/mailFolders/'.$id, $data);
+    }
+
+    public function copy(array $data, string $id): array
+    {
+        EmailFolderCopyValidator::validate($data);
+
+        return MsGraph::post('me/mailFolders/'.$id.'/copy', $data);
+    }
+
+    public function move(array $data, string $id): array
+    {
+        EmailFolderCopyValidator::validate($data);
+
+        return MsGraph::post('me/mailFolders/'.$id.'/copy', $data);
+    }
+
+    public function delete(string $id): void
+    {
+        MsGraph::delete('me/mailFolders/'.$id);
+    }
+
+    protected function fetchSubfolders(array $folders): array
+    {
+        foreach ($folders as &$folder) {
+            $subfolders = MsGraph::get("me/mailFolders/{$folder['id']}/childFolders?\$top=500");
+            $folder['subfolders'] = ! empty($subfolders['value']) ? $this->fetchSubfolders($subfolders['value']) : [];
+        }
+
+        return $folders;
+    }
+
+    protected function sortFolders(array $folders, array $priorityOrder = []): array
+    {
+        // Default folder priority if none provided
+        $defaultPriority = [
+            'Inbox' => 1,
+            'Archive' => 2,
+            'Drafts' => 3,
+            'Sent Items' => 4,
+            'Deleted Items' => 5,
+            'Conversation History' => 6,
+            'Junk Email' => 7,
+        ];
+
+        // Use provided priority order or fallback to default
+        $priority = ! empty($priorityOrder) ? $priorityOrder : $defaultPriority;
+
+        usort($folders, function ($a, $b) use ($priority) {
+            $aPriority = $priority[$a['displayName']] ?? 100;
+            $bPriority = $priority[$b['displayName']] ?? 100;
+
+            return $aPriority === $bPriority
+                ? strcmp($a['displayName'], $b['displayName'])
+                : $aPriority <=> $bPriority;
+        });
+
+        // Sort subfolders recursively
+        foreach ($folders as &$folder) {
+            if (! empty($folder['subfolders'])) {
+                $folder['subfolders'] = $this->sortFolders($folder['subfolders']);
+            }
+        }
+
+        return $folders;
+    }
+}

src/Validators/EmailFolderCopyValidator.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class EmailFolderCopyValidator extends Validator
+{
+    protected static array $allowedParams = [
+        'destinationId',
+    ];
+
+    public static function validate(array $params): array
+    {
+        $validParams = parent::validate($params);
+
+        if (isset($validParams['destinationId']) && ! is_string($validParams['destinationId'])) {
+            throw new InvalidArgumentException('The destinationId must be a string.');
+        }
+
+        return $validParams;
+    }
+}

src/Validators/EmailFolderMoveValidator.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class EmailFolderMoveValidator extends Validator
+{
+    protected static array $allowedParams = [
+        'destinationId',
+    ];
+
+    public static function validate(array $params): array
+    {
+        $validParams = parent::validate($params);
+
+        if (isset($validParams['destinationId']) && ! is_string($validParams['destinationId'])) {
+            throw new InvalidArgumentException('The destinationId must be a string.');
+        }
+
+        return $validParams;
+    }
+}

src/Validators/EmailFolderStoreValidator.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class EmailFolderStoreValidator extends Validator
+{
+    protected static array $allowedParams = [
+        'displayName', 'isHidden',
+    ];
+
+    public static function validate(array $params): array
+    {
+        $validParams = parent::validate($params);
+
+        if (isset($validParams['displayName']) && ! is_string($validParams['displayName'])) {
+            throw new InvalidArgumentException('The displayName must be a string.');
+        }
+
+        if (isset($validParams['isHidden']) && ! is_bool($validParams['isHidden'])) {
+            throw new InvalidArgumentException('The isHidden must be a boolean.');
+        }
+
+        return $validParams;
+    }
+}

src/Validators/EmailFolderUpdateValidator.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class EmailFolderUpdateValidator extends Validator
+{
+    protected static array $allowedParams = [
+        'displayName',
+    ];
+
+    public static function validate(array $params): array
+    {
+        $validParams = parent::validate($params);
+
+        if (isset($validParams['displayName']) && ! is_string($validParams['displayName'])) {
+            throw new InvalidArgumentException('The displayName must be a string.');
+        }
+
+        return $validParams;
+    }
+}

src/Validators/GraphQueryValidator.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class GraphQueryValidator extends Validator
+{
+    protected static array $allowedParams = [
+        '$top', '$skip', '$filter', '$orderby', '$select', '$expand', '$count', '$search', '$format',
+    ];
+}

src/Validators/Validator.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dcblogdev\MsGraph\Validators;
+
+use InvalidArgumentException;
+
+class Validator
+{
+    protected static array $allowedParams = [];
+
+    /**
+     * Validate and filter parameters.
+     *
+     * @param  array  $params  parameters to validate.
+     * @return array Valid parameters.
+     *
+     * @throws InvalidArgumentException If invalid parameters are present.
+     */
+    public static function validate(array $params): array
+    {
+        $allowedParams = static::$allowedParams;
+
+        // Filter out invalid parameters
+        $validParams = array_intersect_key($params, array_flip($allowedParams));
+
+        // Identify invalid parameters
+        $invalidParams = array_diff_key($params, $validParams);
+        if (! empty($invalidParams)) {
+            throw new InvalidArgumentException(sprintf(
+                'Invalid parameters: %s. Allowed parameters: %s.',
+                implode(', ', array_keys($invalidParams)),
+                implode(', ', $allowedParams)
+            ));
+        }
+
+        return $validParams;
+    }
+}

tests/Validators/EmailFolderCopyValidatorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+use Dcblogdev\MsGraph\Validators\EmailFolderCopyValidator;
+
+test('valid parameters are accepted', function () {
+    $response = EmailFolderCopyValidator::validate([
+        'destinationId' => 'demo'
+    ]);
+
+    expect($response)->toEqual([
+        'destinationId' => 'demo'
+    ]);
+});
+
+test('throws exception for unrecognized parameters', function () {
+    EmailFolderCopyValidator::validate([
+        '$top' => 10,
+    ]);
+})->throws(InvalidArgumentException::class, 'Invalid parameters: $top. Allowed parameters: destinationId.');
+
+test('throws exception if destinationId is not a string', function () {
+    EmailFolderCopyValidator::validate(['destinationId' => 1]);
+})->throws(InvalidArgumentException::class, 'The destinationId must be a string.');
+
+test('allows empty input without throwing an exception', function () {
+    $response = EmailFolderCopyValidator::validate([]);
+    expect($response)->toBe([]);
+});

tests/Validators/EmailFolderMoveValidatorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+use Dcblogdev\MsGraph\Validators\EmailFolderMoveValidator;
+
+test('valid parameters are accepted', function () {
+    $response = EmailFolderMoveValidator::validate([
+        'destinationId' => 'demo',
+    ]);
+
+    expect($response)->toEqual([
+        'destinationId' => 'demo',
+    ]);
+});
+
+test('throws exception for unrecognized parameters', function () {
+    EmailFolderMoveValidator::validate([
+        '$top' => 10,
+    ]);
+})->throws(InvalidArgumentException::class, 'Invalid parameters: $top. Allowed parameters: destinationId.');
+
+test('throws exception if destinationId is not a string', function () {
+    EmailFolderMoveValidator::validate(['destinationId' => 1]);
+})->throws(InvalidArgumentException::class, 'The destinationId must be a string.');
+
+test('allows empty input without throwing an exception', function () {
+    $response = EmailFolderMoveValidator::validate([]);
+    expect($response)->toBe([]);
+});