13 files changed, 848 insertions, 0 deletions
diff --git a/lib/public/Notification/AlreadyProcessedException.php b/lib/public/Notification/AlreadyProcessedException.php
new file mode 100644
index 00000000000..162abd81864
--- /dev/null
+++ b/lib/public/Notification/AlreadyProcessedException.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '17.0.0')]
+class AlreadyProcessedException extends \RuntimeException {
+	/**
+	 * @since 17.0.0
+	 */
+	public function __construct() {
+		parent::__construct('Notification is processed already');
+	}
+}
diff --git a/lib/public/Notification/IAction.php b/lib/public/Notification/IAction.php
new file mode 100644
index 00000000000..722dac72826
--- /dev/null
+++ b/lib/public/Notification/IAction.php
@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
+interface IAction {
+	/**
+	 * @since 17.0.0
+	 */
+	public const TYPE_GET = 'GET';
+	/**
+	 * @since 17.0.0
+	 */
+	public const TYPE_POST = 'POST';
+	/**
+	 * @since 17.0.0
+	 */
+	public const TYPE_PUT = 'PUT';
+	/**
+	 * @since 17.0.0
+	 */
+	public const TYPE_DELETE = 'DELETE';
+	/**
+	 * @since 17.0.0
+	 */
+	public const TYPE_WEB = 'WEB';
+
+	/**
+	 * @param string $label
+	 * @return $this
+	 * @throws InvalidValueException if the label is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setLabel(string $label): IAction;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getLabel(): string;
+
+	/**
+	 * @param string $label
+	 * @return $this
+	 * @throws InvalidValueException if the label is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setParsedLabel(string $label): IAction;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getParsedLabel(): string;
+
+	/**
+	 * @param bool $primary
+	 * @return $this
+	 * @since 9.0.0
+	 */
+	public function setPrimary(bool $primary): IAction;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isPrimary(): bool;
+
+	/**
+	 * @param string $link
+	 * @param string $requestType
+	 * @return $this
+	 * @throws InvalidValueException if the link is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setLink(string $link, string $requestType): IAction;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getLink(): string;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getRequestType(): string;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isValid(): bool;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isValidParsed(): bool;
+}
diff --git a/lib/public/Notification/IApp.php b/lib/public/Notification/IApp.php
new file mode 100644
index 00000000000..37c352d44cd
--- /dev/null
+++ b/lib/public/Notification/IApp.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+#[Implementable(since: '9.0.0')]
+interface IApp {
+	/**
+	 * @param INotification $notification
+	 * @throws IncompleteNotificationException When the notification does not have all required fields set
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see IncompleteNotificationException} instead of \InvalidArgumentException
+	 */
+	public function notify(INotification $notification): void;
+
+	/**
+	 * @param INotification $notification
+	 * @since 9.0.0
+	 */
+	public function markProcessed(INotification $notification): void;
+
+	/**
+	 * @param INotification $notification
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getCount(INotification $notification): int;
+}
diff --git a/lib/public/Notification/IDeferrableApp.php b/lib/public/Notification/IDeferrableApp.php
new file mode 100644
index 00000000000..00c7d691b10
--- /dev/null
+++ b/lib/public/Notification/IDeferrableApp.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+#[Implementable(since: '20.0.0')]
+interface IDeferrableApp extends IApp {
+	/**
+	 * Start deferring notifications until `flush()` is called
+	 *
+	 * @since 20.0.0
+	 */
+	public function defer(): void;
+
+	/**
+	 * Send all deferred notifications that have been stored since `defer()` was called
+	 *
+	 * @since 20.0.0
+	 */
+	public function flush(): void;
+}
diff --git a/lib/public/Notification/IDismissableNotifier.php b/lib/public/Notification/IDismissableNotifier.php
new file mode 100644
index 00000000000..d2f649b45a1
--- /dev/null
+++ b/lib/public/Notification/IDismissableNotifier.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * Interface INotifier classes should implement if they want to process notifications
+ * that are dismissed by the user.
+ *
+ * This can be useful if dismissing the notification will leave it in an incomplete
+ * state. The handler can choose to for example do some default action.
+ */
+#[Implementable(since: '18.0.0')]
+interface IDismissableNotifier extends INotifier {
+	/**
+	 * @param INotification $notification
+	 * @throws UnknownNotificationException when the notifier is not in charge of the notification
+	 *
+	 * @since 18.0.0
+	 * @since 30.0.0 Notifiers should throw {@see UnknownNotificationException} instead of \InvalidArgumentException
+	 *  when they did not handle the notification. Throwing \InvalidArgumentException directly is deprecated and will
+	 *  be logged as an error in Nextcloud 39.
+	 */
+	public function dismissNotification(INotification $notification): void;
+}
diff --git a/lib/public/Notification/IManager.php b/lib/public/Notification/IManager.php
new file mode 100644
index 00000000000..207a89344b0
--- /dev/null
+++ b/lib/public/Notification/IManager.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
+interface IManager extends IApp, IPreloadableNotifier {
+	/**
+	 * @param string $appClass The service must implement IApp, otherwise a
+	 *                         \InvalidArgumentException is thrown later
+	 * @since 17.0.0
+	 */
+	public function registerApp(string $appClass): void;
+
+	/**
+	 * @param \Closure $service The service must implement INotifier, otherwise a
+	 *                          \InvalidArgumentException is thrown later
+	 * @param \Closure $info An array with the keys 'id' and 'name' containing
+	 *                       the app id and the app name
+	 * @deprecated 17.0.0 use registerNotifierService instead.
+	 * @since 8.2.0 - Parameter $info was added in 9.0.0
+	 */
+	public function registerNotifier(\Closure $service, \Closure $info);
+
+	/**
+	 * @param string $notifierService The service must implement INotifier, otherwise a
+	 *                                \InvalidArgumentException is thrown later
+	 * @since 17.0.0
+	 * @deprecated 22.0.0 use the IBootStrap registration context
+	 */
+	public function registerNotifierService(string $notifierService): void;
+
+	/**
+	 * @return INotifier[]
+	 * @since 9.0.0
+	 */
+	public function getNotifiers(): array;
+
+	/**
+	 * @return INotification
+	 * @since 9.0.0
+	 */
+	public function createNotification(): INotification;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function hasNotifiers(): bool;
+
+	/**
+	 * @param bool $preparingPushNotification
+	 * @since 14.0.0
+	 */
+	public function setPreparingPushNotification(bool $preparingPushNotification): void;
+
+	/**
+	 * @return bool
+	 * @since 14.0.0
+	 */
+	public function isPreparingPushNotification(): bool;
+
+	/**
+	 * @since 18.0.0
+	 */
+	public function dismissNotification(INotification $notification): void;
+
+	/**
+	 * Start deferring notifications until `flush()` is called
+	 *
+	 * The calling app should only "flush" when it got returned true on the defer call,
+	 * otherwise another app is deferring the sending already.
+	 * @return bool
+	 * @since 20.0.0
+	 */
+	public function defer(): bool;
+
+	/**
+	 * Send all deferred notifications that have been stored since `defer()` was called
+	 *
+	 * @since 20.0.0
+	 */
+	public function flush(): void;
+
+	/**
+	 * Whether the server can use the hosted push notification service
+	 *
+	 * We want to keep offering our push notification service for free, but large
+	 * users overload our infrastructure. For this reason we have to rate-limit the
+	 * use of push notifications. If you need this feature, consider using Nextcloud Enterprise.
+	 *
+	 * @since 23.0.0
+	 */
+	public function isFairUseOfFreePushService(): bool;
+}
diff --git a/lib/public/Notification/INotification.php b/lib/public/Notification/INotification.php
new file mode 100644
index 00000000000..a740678376f
--- /dev/null
+++ b/lib/public/Notification/INotification.php
@@ -0,0 +1,331 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+#[Consumable(since: '9.0.0')]
+interface INotification {
+	/**
+	 * @param string $app
+	 * @return $this
+	 * @throws InvalidValueException if the app id is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setApp(string $app): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getApp(): string;
+
+	/**
+	 * @param string $user
+	 * @return $this
+	 * @throws InvalidValueException if the user id is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setUser(string $user): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getUser(): string;
+
+	/**
+	 * @param \DateTime $dateTime
+	 * @return $this
+	 * @throws InvalidValueException if the $dateTime is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setDateTime(\DateTime $dateTime): INotification;
+
+	/**
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	public function getDateTime(): \DateTime;
+
+	/**
+	 * @param string $type
+	 * @param string $id
+	 * @return $this
+	 * @throws InvalidValueException if the object type or id is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setObject(string $type, string $id): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectType(): string;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectId(): string;
+
+	/**
+	 * @param string $subject
+	 * @param array $parameters
+	 * @return $this
+	 * @throws InvalidValueException if the subject or parameters are invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setSubject(string $subject, array $parameters = []): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getSubject(): string;
+
+	/**
+	 * @return array
+	 * @since 9.0.0
+	 */
+	public function getSubjectParameters(): array;
+
+	/**
+	 * Set a parsed subject
+	 *
+	 * HTML is not allowed in the parsed subject and will be escaped
+	 * automatically by the clients. You can use the RichObjectString system
+	 * provided by the Nextcloud server to highlight important parameters via
+	 * the setRichSubject method.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
+	 * @param string $subject
+	 * @return $this
+	 * @throws InvalidValueException if the subject is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setParsedSubject(string $subject): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getParsedSubject(): string;
+
+	/**
+	 * Set a RichObjectString subject
+	 *
+	 * HTML is not allowed in the rich subject and will be escaped automatically
+	 * by the clients, but you can use the RichObjectString system provided by
+	 * the Nextcloud server to highlight important parameters.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
+	 * @param string $subject
+	 * @param array<string, array<string, string>> $parameters
+	 * @return $this
+	 * @throws InvalidValueException if the subject or parameters are invalid
+	 * @since 11.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setRichSubject(string $subject, array $parameters = []): INotification;
+
+	/**
+	 * @return string
+	 * @since 11.0.0
+	 */
+	public function getRichSubject(): string;
+
+	/**
+	 * @return array[]
+	 * @since 11.0.0
+	 */
+	public function getRichSubjectParameters(): array;
+
+	/**
+	 * @param string $message
+	 * @param array $parameters
+	 * @return $this
+	 * @throws InvalidValueException if the message or parameters are invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setMessage(string $message, array $parameters = []): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMessage(): string;
+
+	/**
+	 * @return array
+	 * @since 9.0.0
+	 */
+	public function getMessageParameters(): array;
+
+	/**
+	 * Set a parsed message
+	 *
+	 * HTML is not allowed in the parsed message and will be escaped
+	 * automatically by the clients. You can use the RichObjectString system
+	 * provided by the Nextcloud server to highlight important parameters via
+	 * the setRichMessage method.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
+	 * @param string $message
+	 * @return $this
+	 * @throws InvalidValueException if the message is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setParsedMessage(string $message): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getParsedMessage(): string;
+
+	/**
+	 * Set a RichObjectString message
+	 *
+	 * HTML is not allowed in the rich message and will be escaped automatically
+	 * by the clients, but you can use the RichObjectString system provided by
+	 * the Nextcloud server to highlight important parameters.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
+	 * @param string $message
+	 * @param array<string, array<string, string>> $parameters
+	 * @return $this
+	 * @throws InvalidValueException if the message or parameters are invalid
+	 * @since 11.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setRichMessage(string $message, array $parameters = []): INotification;
+
+	/**
+	 * @return string
+	 * @since 11.0.0
+	 */
+	public function getRichMessage(): string;
+
+	/**
+	 * @return array[]
+	 * @since 11.0.0
+	 */
+	public function getRichMessageParameters(): array;
+
+	/**
+	 * @param string $link
+	 * @return $this
+	 * @throws InvalidValueException if the link is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setLink(string $link): INotification;
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getLink(): string;
+
+	/**
+	 * Set the absolute url for the icon (should be colored black or not have a color)
+	 *
+	 * It's automatically color inverted by clients when needed
+	 *
+	 * @param string $icon
+	 * @return $this
+	 * @throws InvalidValueException if the icon is invalid
+	 * @since 11.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function setIcon(string $icon): INotification;
+
+	/**
+	 * Get the absolute url for the icon (should be colored black or not have a color)
+	 *
+	 * It's automatically color inverted by clients when needed
+	 *
+	 * @return string
+	 * @since 11.0.0
+	 */
+	public function getIcon(): string;
+
+	/**
+	 * @return $this
+	 * @throws InvalidValueException if the app is not allowed to send priority notifications
+	 * @since 31.0.0
+	 */
+	public function setPriorityNotification(bool $priorityNotification): INotification;
+
+	/**
+	 * @since 31.0.0
+	 */
+	public function isPriorityNotification(): bool;
+
+	/**
+	 * @return IAction
+	 * @since 9.0.0
+	 */
+	public function createAction(): IAction;
+
+	/**
+	 * @param IAction $action
+	 * @return $this
+	 * @throws InvalidValueException if the action is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function addAction(IAction $action): INotification;
+
+	/**
+	 * @return IAction[]
+	 * @since 9.0.0
+	 */
+	public function getActions(): array;
+
+	/**
+	 * @param IAction $action
+	 * @return $this
+	 * @throws InvalidValueException if the action is invalid
+	 * @since 9.0.0
+	 * @since 30.0.0 throws {@see InvalidValueException} instead of \InvalidArgumentException
+	 */
+	public function addParsedAction(IAction $action): INotification;
+
+	/**
+	 * @return IAction[]
+	 * @since 9.0.0
+	 */
+	public function getParsedActions(): array;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isValid(): bool;
+
+	/**
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isValidParsed(): bool;
+}
diff --git a/lib/public/Notification/INotifier.php b/lib/public/Notification/INotifier.php
new file mode 100644
index 00000000000..b6851e3dfb3
--- /dev/null
+++ b/lib/public/Notification/INotifier.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * Please consider implementing {@see IPreloadableNotifier} to improve performance. It allows to
+ * preload and cache data for many notifications at once instead of loading the data for each
+ * prepared notification separately.
+ */
+#[Implementable(since: '9.0.0')]
+interface INotifier {
+	/**
+	 * Identifier of the notifier, only use [a-z0-9_]
+	 *
+	 * @return string
+	 * @since 17.0.0
+	 */
+	public function getID(): string;
+
+	/**
+	 * Human-readable name describing the notifier
+	 *
+	 * @return string
+	 * @since 17.0.0
+	 */
+	public function getName(): string;
+
+	/**
+	 * @param INotification $notification
+	 * @param string $languageCode The code of the language that should be used to prepare the notification
+	 * @return INotification
+	 * @throws UnknownNotificationException When the notification was not prepared by a notifier
+	 * @throws AlreadyProcessedException When the notification is not needed anymore and should be deleted
+	 * @throws IncompleteParsedNotificationException Only to be thrown by the {@see IManager}
+	 * @since 9.0.0
+	 * @since 30.0.0 Notifiers should throw {@see UnknownNotificationException} instead of \InvalidArgumentException
+	 *  when they did not handle the notification. Throwing \InvalidArgumentException directly is deprecated and will
+	 *  be logged as an error in Nextcloud 39.
+	 * @since 30.0.0 Throws {@see IncompleteParsedNotificationException} when not all required fields
+	 *  are set at the end of the manager or after a INotifier that claimed to have parsed the notification.
+	 */
+	public function prepare(INotification $notification, string $languageCode): INotification;
+}
diff --git a/lib/public/Notification/IPreloadableNotifier.php b/lib/public/Notification/IPreloadableNotifier.php
new file mode 100644
index 00000000000..2bdcd84d254
--- /dev/null
+++ b/lib/public/Notification/IPreloadableNotifier.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Implementable;
+
+/**
+ * Allow notifier implementations to preload and cache data for many notifications at once to
+ * improve performance by, for example, bundling SQL queries.
+ */
+#[Implementable(since: '32.0.0')]
+interface IPreloadableNotifier extends INotifier {
+	/**
+	 * This method provides a way for notifier implementations to preload and cache data for many
+	 * notifications. The data is meant to be consumed later in the {@see INotifier::prepare()}
+	 * method to improve performance.
+	 *
+	 * @since 32.0.0
+	 *
+	 * @param INotification[] $notifications The notifications which are about to be prepared in the next step.
+	 * @param string $languageCode The code of the language that should be used to prepare the notification.
+	 */
+	public function preloadDataForParsing(array $notifications, string $languageCode): void;
+}
diff --git a/lib/public/Notification/IncompleteNotificationException.php b/lib/public/Notification/IncompleteNotificationException.php
new file mode 100644
index 00000000000..49d388ebee6
--- /dev/null
+++ b/lib/public/Notification/IncompleteNotificationException.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+/**
+ * Thrown when {@see \OCP\Notification\IManager::notify()} is called with a notification
+ * that does not have all required fields set:
+ *
+ * - app
+ * - user
+ * - dateTime
+ * - objectType
+ * - objectId
+ * - subject
+ */
+#[Catchable(since: '30.0.0')]
+class IncompleteNotificationException extends \InvalidArgumentException {
+}
diff --git a/lib/public/Notification/IncompleteParsedNotificationException.php b/lib/public/Notification/IncompleteParsedNotificationException.php
new file mode 100644
index 00000000000..c31ab129fd4
--- /dev/null
+++ b/lib/public/Notification/IncompleteParsedNotificationException.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+/**
+ * Thrown when {@see \OCP\Notification\IManager::prepare()} is called with a notification
+ * that does not have all required fields set at the end of the manager or after a INotifier
+ * that claimed to have parsed the notification.
+ *
+ * Required fields are:
+ *
+ * - app
+ * - user
+ * - dateTime
+ * - objectType
+ * - objectId
+ * - parsedSubject
+ */
+#[Catchable(since: '30.0.0')]
+class IncompleteParsedNotificationException extends \InvalidArgumentException {
+}
diff --git a/lib/public/Notification/InvalidValueException.php b/lib/public/Notification/InvalidValueException.php
new file mode 100644
index 00000000000..ec52381ee3c
--- /dev/null
+++ b/lib/public/Notification/InvalidValueException.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Catchable;
+
+#[Catchable(since: '30.0.0')]
+class InvalidValueException extends \InvalidArgumentException {
+	/**
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		protected string $field,
+		?\Throwable $previous = null,
+	) {
+		parent::__construct('Value provided for ' . $field . ' is not valid', previous: $previous);
+	}
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function getFieldIdentifier(): string {
+		return $this->field;
+	}
+}
diff --git a/lib/public/Notification/UnknownNotificationException.php b/lib/public/Notification/UnknownNotificationException.php
new file mode 100644
index 00000000000..976d9179592
--- /dev/null
+++ b/lib/public/Notification/UnknownNotificationException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '30.0.0')]
+class UnknownNotificationException extends \InvalidArgumentException {
+}