Merge pull request #45435 from nextcloud/feat/dav/upcoming-events-api

feat(dav): Add an API for upcoming events

10 files changed, 524 insertions, 0 deletions

diff --git a/apps/dav/appinfo/routes.php b/apps/dav/appinfo/routes.php
index 820b034d7a7..91c1ba58ea2 100644
--- a/apps/dav/appinfo/routes.php
+++ b/apps/dav/appinfo/routes.php
@@ -14,6 +14,7 @@ return [
 	],
 	'ocs' => [
 		['name' => 'direct#getUrl', 'url' => '/api/v1/direct', 'verb' => 'POST'],
+		['name' => 'upcoming_events#getEvents', 'url' => '/api/v1/events/upcoming', 'verb' => 'GET'],
 		['name' => 'out_of_office#getCurrentOutOfOfficeData', 'url' => '/api/v1/outOfOffice/{userId}/now', 'verb' => 'GET'],
 		['name' => 'out_of_office#getOutOfOffice', 'url' => '/api/v1/outOfOffice/{userId}', 'verb' => 'GET'],
 		['name' => 'out_of_office#setOutOfOffice', 'url' => '/api/v1/outOfOffice/{userId}', 'verb' => 'POST'],
diff --git a/apps/dav/composer/composer/autoload_classmap.php b/apps/dav/composer/composer/autoload_classmap.php
index adbf0a23d36..e79904221d3 100644
--- a/apps/dav/composer/composer/autoload_classmap.php
+++ b/apps/dav/composer/composer/autoload_classmap.php
@@ -116,6 +116,8 @@ return array(
     'OCA\\DAV\\CalDAV\\Trashbin\\Plugin' => $baseDir . '/../lib/CalDAV/Trashbin/Plugin.php',
     'OCA\\DAV\\CalDAV\\Trashbin\\RestoreTarget' => $baseDir . '/../lib/CalDAV/Trashbin/RestoreTarget.php',
     'OCA\\DAV\\CalDAV\\Trashbin\\TrashbinHome' => $baseDir . '/../lib/CalDAV/Trashbin/TrashbinHome.php',
+    'OCA\\DAV\\CalDAV\\UpcomingEvent' => $baseDir . '/../lib/CalDAV/UpcomingEvent.php',
+    'OCA\\DAV\\CalDAV\\UpcomingEventsService' => $baseDir . '/../lib/CalDAV/UpcomingEventsService.php',
     'OCA\\DAV\\CalDAV\\Validation\\CalDavValidatePlugin' => $baseDir . '/../lib/CalDAV/Validation/CalDavValidatePlugin.php',
     'OCA\\DAV\\CalDAV\\WebcalCaching\\Plugin' => $baseDir . '/../lib/CalDAV/WebcalCaching/Plugin.php',
     'OCA\\DAV\\CalDAV\\WebcalCaching\\RefreshWebcalService' => $baseDir . '/../lib/CalDAV/WebcalCaching/RefreshWebcalService.php',
@@ -213,6 +215,7 @@ return array(
     'OCA\\DAV\\Controller\\DirectController' => $baseDir . '/../lib/Controller/DirectController.php',
     'OCA\\DAV\\Controller\\InvitationResponseController' => $baseDir . '/../lib/Controller/InvitationResponseController.php',
     'OCA\\DAV\\Controller\\OutOfOfficeController' => $baseDir . '/../lib/Controller/OutOfOfficeController.php',
+    'OCA\\DAV\\Controller\\UpcomingEventsController' => $baseDir . '/../lib/Controller/UpcomingEventsController.php',
     'OCA\\DAV\\DAV\\CustomPropertiesBackend' => $baseDir . '/../lib/DAV/CustomPropertiesBackend.php',
     'OCA\\DAV\\DAV\\GroupPrincipalBackend' => $baseDir . '/../lib/DAV/GroupPrincipalBackend.php',
     'OCA\\DAV\\DAV\\PublicAuth' => $baseDir . '/../lib/DAV/PublicAuth.php',
diff --git a/apps/dav/composer/composer/autoload_static.php b/apps/dav/composer/composer/autoload_static.php
index 975af1af81f..71bb80b39b7 100644
--- a/apps/dav/composer/composer/autoload_static.php
+++ b/apps/dav/composer/composer/autoload_static.php
@@ -131,6 +131,8 @@ class ComposerStaticInitDAV
         'OCA\\DAV\\CalDAV\\Trashbin\\Plugin' => __DIR__ . '/..' . '/../lib/CalDAV/Trashbin/Plugin.php',
         'OCA\\DAV\\CalDAV\\Trashbin\\RestoreTarget' => __DIR__ . '/..' . '/../lib/CalDAV/Trashbin/RestoreTarget.php',
         'OCA\\DAV\\CalDAV\\Trashbin\\TrashbinHome' => __DIR__ . '/..' . '/../lib/CalDAV/Trashbin/TrashbinHome.php',
+        'OCA\\DAV\\CalDAV\\UpcomingEvent' => __DIR__ . '/..' . '/../lib/CalDAV/UpcomingEvent.php',
+        'OCA\\DAV\\CalDAV\\UpcomingEventsService' => __DIR__ . '/..' . '/../lib/CalDAV/UpcomingEventsService.php',
         'OCA\\DAV\\CalDAV\\Validation\\CalDavValidatePlugin' => __DIR__ . '/..' . '/../lib/CalDAV/Validation/CalDavValidatePlugin.php',
         'OCA\\DAV\\CalDAV\\WebcalCaching\\Plugin' => __DIR__ . '/..' . '/../lib/CalDAV/WebcalCaching/Plugin.php',
         'OCA\\DAV\\CalDAV\\WebcalCaching\\RefreshWebcalService' => __DIR__ . '/..' . '/../lib/CalDAV/WebcalCaching/RefreshWebcalService.php',
@@ -228,6 +230,7 @@ class ComposerStaticInitDAV
         'OCA\\DAV\\Controller\\DirectController' => __DIR__ . '/..' . '/../lib/Controller/DirectController.php',
         'OCA\\DAV\\Controller\\InvitationResponseController' => __DIR__ . '/..' . '/../lib/Controller/InvitationResponseController.php',
         'OCA\\DAV\\Controller\\OutOfOfficeController' => __DIR__ . '/..' . '/../lib/Controller/OutOfOfficeController.php',
+        'OCA\\DAV\\Controller\\UpcomingEventsController' => __DIR__ . '/..' . '/../lib/Controller/UpcomingEventsController.php',
         'OCA\\DAV\\DAV\\CustomPropertiesBackend' => __DIR__ . '/..' . '/../lib/DAV/CustomPropertiesBackend.php',
         'OCA\\DAV\\DAV\\GroupPrincipalBackend' => __DIR__ . '/..' . '/../lib/DAV/GroupPrincipalBackend.php',
         'OCA\\DAV\\DAV\\PublicAuth' => __DIR__ . '/..' . '/../lib/DAV/PublicAuth.php',
diff --git a/apps/dav/lib/CalDAV/UpcomingEvent.php b/apps/dav/lib/CalDAV/UpcomingEvent.php
new file mode 100644
index 00000000000..26760ffedd5
--- /dev/null
+++ b/apps/dav/lib/CalDAV/UpcomingEvent.php
@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\DAV\CalDAV;
+
+use JsonSerializable;
+use OCA\DAV\ResponseDefinitions;
+
+class UpcomingEvent implements JsonSerializable {
+	public function __construct(private string $uri,
+		private ?int $recurrenceId,
+		private string $calendarUri,
+		private ?int $start,
+		private ?string $summary,
+		private ?string $location,
+		private ?string $calendarAppUrl) {
+	}
+
+	public function getUri(): string {
+		return $this->uri;
+	}
+
+	public function getRecurrenceId(): ?int {
+		return $this->recurrenceId;
+	}
+
+	public function getCalendarUri(): string {
+		return $this->calendarUri;
+	}
+
+	public function getStart(): ?int {
+		return $this->start;
+	}
+
+	public function getSummary(): ?string {
+		return $this->summary;
+	}
+
+	public function getLocation(): ?string {
+		return $this->location;
+	}
+
+	public function getCalendarAppUrl(): ?string {
+		return $this->calendarAppUrl;
+	}
+
+	/**
+	 * @see ResponseDefinitions
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'uri' => $this->uri,
+			'recurrenceId' => $this->recurrenceId,
+			'calendarUri' => $this->calendarUri,
+			'start' => $this->start,
+			'summary' => $this->summary,
+			'location' => $this->location,
+			'calendarAppUrl' => $this->calendarAppUrl,
+		];
+	}
+}
diff --git a/apps/dav/lib/CalDAV/UpcomingEventsService.php b/apps/dav/lib/CalDAV/UpcomingEventsService.php
new file mode 100644
index 00000000000..04ab1be19b4
--- /dev/null
+++ b/apps/dav/lib/CalDAV/UpcomingEventsService.php
@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\DAV\CalDAV;
+
+use OCP\App\IAppManager;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\Calendar\IManager;
+use OCP\IURLGenerator;
+use OCP\IUserManager;
+use function array_map;
+
+class UpcomingEventsService {
+	public function __construct(private IManager $calendarManager,
+		private ITimeFactory $timeFactory,
+		private IUserManager $userManager,
+		private IAppManager $appManager,
+		private IURLGenerator $urlGenerator) {
+	}
+
+	/**
+	 * @return UpcomingEvent[]
+	 */
+	public function getEvents(string $userId, ?string $location = null): array {
+		$searchQuery = $this->calendarManager->newQuery('principals/users/' . $userId);
+		if ($location !== null) {
+			$searchQuery->addSearchProperty('LOCATION');
+			$searchQuery->setSearchPattern($location);
+		}
+		$searchQuery->addType('VEVENT');
+		$searchQuery->setLimit(3);
+		$now = $this->timeFactory->now();
+		$searchQuery->setTimerangeStart($now->modify('-1 minute'));
+		$searchQuery->setTimerangeEnd($now->modify('+1 month'));
+
+		$events = $this->calendarManager->searchForPrincipal($searchQuery);
+		$calendarAppEnabled = $this->appManager->isEnabledForUser(
+			'calendar',
+			$this->userManager->get($userId),
+		);
+
+		return array_map(fn (array $event) => new UpcomingEvent(
+			$event['uri'],
+			($event['objects'][0]['RECURRENCE-ID'][0] ?? null)?->getTimeStamp(),
+			$event['calendar-uri'],
+			$event['objects'][0]['DTSTART'][0]?->getTimestamp(),
+			$event['objects'][0]['SUMMARY'][0] ?? null,
+			$event['objects'][0]['LOCATION'][0] ?? null,
+			match ($calendarAppEnabled) {
+				// TODO: create a named, deep route in calendar
+				// TODO: it's a code smell to just assume this route exists, find an abstraction
+				true => $this->urlGenerator->linkToRouteAbsolute('calendar.view.index'),
+				false => null,
+			},
+		), $events);
+	}
+
+}
diff --git a/apps/dav/lib/Controller/UpcomingEventsController.php b/apps/dav/lib/Controller/UpcomingEventsController.php
new file mode 100644
index 00000000000..879fe05d613
--- /dev/null
+++ b/apps/dav/lib/Controller/UpcomingEventsController.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\DAV\Controller;
+
+use OCA\DAV\AppInfo\Application;
+use OCA\DAV\CalDAV\UpcomingEvent;
+use OCA\DAV\CalDAV\UpcomingEventsService;
+use OCA\DAV\ResponseDefinitions;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\OCSController;
+use OCP\IRequest;
+
+/**
+ * @psalm-import-type DAVUpcomingEvent from ResponseDefinitions
+ */
+class UpcomingEventsController extends OCSController {
+	private ?string $userId;
+	private UpcomingEventsService $service;
+
+	public function __construct(
+		IRequest $request,
+		?string $userId,
+		UpcomingEventsService $service) {
+		parent::__construct(Application::APP_ID, $request);
+
+		$this->userId = $userId;
+		$this->service = $service;
+	}
+
+	/**
+	 * Get information about upcoming events
+	 *
+	 * @param string|null $location location/URL to filter by
+	 * @return DataResponse<Http::STATUS_OK, array{events: DAVUpcomingEvent[]}, array{}>|DataResponse<Http::STATUS_UNAUTHORIZED, null, array{}>
+	 *
+	 * 200: Upcoming events
+	 * 401: When not authenticated
+	 */
+	#[NoAdminRequired]
+	public function getEvents(?string $location = null): DataResponse {
+		if ($this->userId === null) {
+			return new DataResponse(null, Http::STATUS_UNAUTHORIZED);
+		}
+
+		return new DataResponse([
+			'events' => array_map(fn (UpcomingEvent $e) => $e->jsonSerialize(), $this->service->getEvents(
+				$this->userId,
+				$location,
+			)),
+		]);
+	}
+
+}
diff --git a/apps/dav/lib/ResponseDefinitions.php b/apps/dav/lib/ResponseDefinitions.php
index 2dc0d4e8dbd..3deafad6704 100644
--- a/apps/dav/lib/ResponseDefinitions.php
+++ b/apps/dav/lib/ResponseDefinitions.php
@@ -9,6 +9,8 @@ declare(strict_types=1);
 
 namespace OCA\DAV;
 
+use OCA\DAV\CalDAV\UpcomingEvent;
+
 /**
  * @psalm-type DAVOutOfOfficeDataCommon = array{
  *      userId: string,
@@ -31,6 +33,15 @@ namespace OCA\DAV;
  *     endDate: int,
  *     shortMessage: string,
  * }
+ *
+ * @see UpcomingEvent::jsonSerialize
+ * @psalm-type DAVUpcomingEvent = array{
+ *      uri: string,
+ *      calendarUri: string,
+ *      start: ?int,
+ *      summary: ?string,
+ *      location: ?string,
+ *  }
  */
 class ResponseDefinitions {
 }
diff --git a/apps/dav/openapi.json b/apps/dav/openapi.json
index 946a603f44d..5d3e292a7ef 100644
--- a/apps/dav/openapi.json
+++ b/apps/dav/openapi.json
@@ -153,6 +153,37 @@
                         "nullable": true
                     }
                 }
+            },
+            "UpcomingEvent": {
+                "type": "object",
+                "required": [
+                    "uri",
+                    "calendarUri",
+                    "start",
+                    "summary",
+                    "location"
+                ],
+                "properties": {
+                    "uri": {
+                        "type": "string"
+                    },
+                    "calendarUri": {
+                        "type": "string"
+                    },
+                    "start": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
+                    },
+                    "summary": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "location": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                }
             }
         }
     },
@@ -336,6 +367,125 @@
                 }
             }
         },
+        "/ocs/v2.php/apps/dav/api/v1/events/upcoming": {
+            "get": {
+                "operationId": "upcoming_events-get-events",
+                "summary": "Get information about upcoming events",
+                "tags": [
+                    "upcoming_events"
+                ],
+                "security": [
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "requestBody": {
+                    "required": false,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "properties": {
+                                    "location": {
+                                        "type": "string",
+                                        "nullable": true,
+                                        "description": "location/URL to filter by"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "parameters": [
+                    {
+                        "name": "OCS-APIRequest",
+                        "in": "header",
+                        "description": "Required to be true for the API request to pass",
+                        "required": true,
+                        "schema": {
+                            "type": "boolean",
+                            "default": true
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Upcoming events",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "type": "object",
+                                                    "required": [
+                                                        "events"
+                                                    ],
+                                                    "properties": {
+                                                        "events": {
+                                                            "type": "array",
+                                                            "items": {
+                                                                "$ref": "#/components/schemas/UpcomingEvent"
+                                                            }
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "description": "When not authenticated",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "nullable": true
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/ocs/v2.php/apps/dav/api/v1/outOfOffice/{userId}/now": {
             "get": {
                 "operationId": "out_of_office-get-current-out-of-office-data",
diff --git a/apps/dav/tests/unit/Controller/UpcomingEventsControllerTest.php b/apps/dav/tests/unit/Controller/UpcomingEventsControllerTest.php
new file mode 100644
index 00000000000..9e5c03bb245
--- /dev/null
+++ b/apps/dav/tests/unit/Controller/UpcomingEventsControllerTest.php
@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\DAV\Tests\Unit\DAV\Service;
+
+use OCA\DAV\CalDAV\UpcomingEvent;
+use OCA\DAV\CalDAV\UpcomingEventsService;
+use OCA\DAV\Controller\UpcomingEventsController;
+use OCP\IRequest;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class UpcomingEventsControllerTest extends TestCase {
+
+	private IRequest|MockObject $request;
+	private UpcomingEventsService|MockObject $service;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->request = $this->createMock(IRequest::class);
+		$this->service = $this->createMock(UpcomingEventsService::class);
+	}
+
+	public function testGetEventsAnonymously() {
+		$controller = new UpcomingEventsController(
+			$this->request,
+			null,
+			$this->service,
+		);
+
+		$response = $controller->getEvents('https://cloud.example.com/call/123');
+
+		self::assertNull($response->getData());
+		self::assertSame(401, $response->getStatus());
+	}
+
+	public function testGetEventsByLocation() {
+		$controller = new UpcomingEventsController(
+			$this->request,
+			'u1',
+			$this->service,
+		);
+		$this->service->expects(self::once())
+			->method('getEvents')
+			->with('u1', 'https://cloud.example.com/call/123')
+			->willReturn([
+				new UpcomingEvent(
+					'abc-123',
+					null,
+					'personal',
+					123,
+					'Test',
+					'https://cloud.example.com/call/123',
+					null,
+				),
+			]);
+
+		$response = $controller->getEvents('https://cloud.example.com/call/123');
+
+		self::assertNotNull($response->getData());
+		self::assertIsArray($response->getData());
+		self::assertCount(1, $response->getData()['events']);
+		self::assertSame(200, $response->getStatus());
+		$event1 = $response->getData()['events'][0];
+		self::assertEquals('abc-123', $event1['uri']);
+	}
+}
diff --git a/apps/dav/tests/unit/Service/UpcomingEventsServiceTest.php b/apps/dav/tests/unit/Service/UpcomingEventsServiceTest.php
new file mode 100644
index 00000000000..ecb0268c8c2
--- /dev/null
+++ b/apps/dav/tests/unit/Service/UpcomingEventsServiceTest.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\DAV\Tests\Unit\DAV\Service;
+
+use DateTimeImmutable;
+use OCA\DAV\CalDAV\UpcomingEventsService;
+use OCP\App\IAppManager;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\Calendar\ICalendarQuery;
+use OCP\Calendar\IManager;
+use OCP\IURLGenerator;
+use OCP\IUserManager;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class UpcomingEventsServiceTest extends TestCase {
+
+	private MockObject|IManager $calendarManager;
+	private ITimeFactory|MockObject $timeFactory;
+	private IUserManager|MockObject $userManager;
+	private IAppManager|MockObject $appManager;
+	private IURLGenerator|MockObject $urlGenerator;
+	private UpcomingEventsService $service;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->calendarManager = $this->createMock(IManager::class);
+		$this->timeFactory = $this->createMock(ITimeFactory::class);
+		$this->userManager = $this->createMock(IUserManager::class);
+		$this->appManager = $this->createMock(IAppManager::class);
+		$this->urlGenerator = $this->createMock(IURLGenerator::class);
+
+		$this->service = new UpcomingEventsService(
+			$this->calendarManager,
+			$this->timeFactory,
+			$this->userManager,
+			$this->appManager,
+			$this->urlGenerator,
+		);
+	}
+
+	public function testGetEventsByLocation(): void {
+		$now = new DateTimeImmutable('2024-07-08T18:20:20Z');
+		$this->timeFactory->method('now')
+			->willReturn($now);
+		$query = $this->createMock(ICalendarQuery::class);
+		$this->appManager->method('isEnabledForUser')->willReturn(false);
+		$this->calendarManager->method('newQuery')
+			->with('principals/users/user1')
+			->willReturn($query);
+		$query->expects(self::once())
+			->method('addSearchProperty')
+			->with('LOCATION');
+		$query->expects(self::once())
+			->method('setSearchPattern')
+			->with('https://cloud.example.com/call/123');
+		$this->calendarManager->expects(self::once())
+			->method('searchForPrincipal')
+			->with($query)
+			->willReturn([
+				[
+					'uri' => 'ev1',
+					'calendar-key' => '1',
+					'calendar-uri' => 'personal',
+					'objects' => [
+						0 => [
+							'DTSTART' => [
+								new DateTimeImmutable('now'),
+							],
+						],
+					],
+				],
+			]);
+
+		$events = $this->service->getEvents('user1', 'https://cloud.example.com/call/123');
+
+		self::assertCount(1, $events);
+		$event1 = $events[0];
+		self::assertEquals('ev1', $event1->getUri());
+	}
+}