feat: add OCS routes for mailbox and mail listing

Signed-off-by: Jana Peper <jana.peper@nextcloud.com>

Author: janepie

lib/Controller/MailboxesApiController.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Mail\Controller;
+
+use OCA\Mail\Contracts\IMailManager;
+use OCA\Mail\Contracts\IMailSearch;
+use OCA\Mail\Contracts\IUserPreferences;
+use OCA\Mail\ResponseDefinitions;
+use OCA\Mail\Service\AccountService;
+use OCA\Mail\Service\AliasesService;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\ApiRoute;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\OCSController;
+use OCP\IRequest;
+
+/**
+ * @psalm-import-type MailAccountListResponse from ResponseDefinitions
+ */
+class MailboxesApiController extends OCSController {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly ?string $userId,
+		private IMailManager $mailManager,
+		private readonly AccountService $accountService,
+		private readonly AliasesService $aliasesService,
+		private IMailSearch $mailSearch,
+		private IUserPreferences $preferences,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/**
+	 * List all mailboxes of an account of the user which is currently logged-in
+	 *
+	 * @return DataResponse<Http::STATUS_OK, string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{}, array{}>
+	 *
+	 * 200: Mailbox list
+	 * 404: User was not logged in
+	 */
+	#[ApiRoute(verb: 'GET', url: '/mailbox/list')]
+	#[NoAdminRequired]
+	#[NoCSRFRequired]
+	public function list(int $accountId): DataResponse {
+		$userId = $this->userId;
+		if ($userId === null) {
+			return new DataResponse([], Http::STATUS_NOT_FOUND);
+		}
+
+		$account = $this->accountService->find($userId, $accountId);
+
+		$mailboxes = $this->mailManager->getMailboxes($account);
+		return new DataResponse(json_encode($mailboxes), Http::STATUS_OK);
+	}
+
+
+
+	/**
+	 * List the messages in a mailbox of the user which is currently logged-in
+	 *
+	 * @return DataResponse<Http::STATUS_OK, string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{}, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{}, array{}>
+	 *
+	 * 200: Message list
+	 * 403: User cannot access this mailbox
+	 * 404: User was not logged in
+	 */
+	#[ApiRoute(verb: 'GET', url: '/mailbox/messages/list')]
+	#[NoAdminRequired]
+	#[NoCSRFRequired]
+	public function listMessages(int $mailboxId,
+		?int $cursor = null,
+		?string $filter = null,
+		?int $limit = null,
+		?string $view = null): DataResponse {
+		$userId = $this->userId;
+		if ($userId === null) {
+			return new DataResponse([], Http::STATUS_NOT_FOUND);
+		}
+		try {
+			$mailbox = $this->mailManager->getMailbox($userId, $mailboxId);
+			$account = $this->accountService->find($userId, $mailbox->getAccountId());
+		} catch (DoesNotExistException $e) {
+			return new DataResponse([], Http::STATUS_FORBIDDEN);
+		}
+
+		$sort = $this->preferences->getPreference($userId, 'sort-order', 'newest') === 'newest' ? IMailSearch::ORDER_NEWEST_FIRST: IMailSearch::ORDER_OLDEST_FIRST;
+
+		$view = $view === 'singleton' ? IMailSearch::VIEW_SINGLETON : IMailSearch::VIEW_THREADED;
+
+		$messages = $this->mailSearch->findMessages(
+			$account,
+			$mailbox,
+			$sort,
+			$filter === '' ? null : $filter,
+			$cursor,
+			$limit,
+			$userId,
+			$view
+		);
+		return new DataResponse(json_encode($messages), Http::STATUS_OK);
+	}
+}