9 files changed, 1032 insertions, 0 deletions
diff --git a/lib/public/Comments/CommentsEntityEvent.php b/lib/public/Comments/CommentsEntityEvent.php
new file mode 100644
index 00000000000..39568151b61
--- /dev/null
+++ b/lib/public/Comments/CommentsEntityEvent.php
@@ -0,0 +1,62 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * Class CommentsEntityEvent
+ *
+ * @since 9.1.0
+ * @since 28.0.0 Dispatched as a typed event
+ */
+class CommentsEntityEvent extends Event {
+	/**
+	 * @since 9.1.0
+	 * @deprecated 22.0.0 - Listen to the typed event instead.
+	 */
+	public const EVENT_ENTITY = 'OCP\Comments\ICommentsManager::registerEntity';
+
+	/** @var \Closure[] */
+	protected $collections;
+
+	/**
+	 * DispatcherEvent constructor.
+	 *
+	 * @since 9.1.0
+	 */
+	public function __construct() {
+		parent::__construct();
+		$this->collections = [];
+	}
+
+	/**
+	 * @param string $name
+	 * @param \Closure $entityExistsFunction The closure should take one
+	 *                                       argument, which is the id of the entity, that comments
+	 *                                       should be handled for. The return should then be bool,
+	 *                                       depending on whether comments are allowed (true) or not.
+	 * @throws \OutOfBoundsException when the entity name is already taken
+	 * @since 9.1.0
+	 */
+	public function addEntityCollection($name, \Closure $entityExistsFunction) {
+		if (isset($this->collections[$name])) {
+			throw new \OutOfBoundsException('Duplicate entity name "' . $name . '"');
+		}
+
+		$this->collections[$name] = $entityExistsFunction;
+	}
+
+	/**
+	 * @return \Closure[]
+	 * @since 9.1.0
+	 */
+	public function getEntityCollections() {
+		return $this->collections;
+	}
+}
diff --git a/lib/public/Comments/CommentsEvent.php b/lib/public/Comments/CommentsEvent.php
new file mode 100644
index 00000000000..04d592d4f1e
--- /dev/null
+++ b/lib/public/Comments/CommentsEvent.php
@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * Class CommentsEvent
+ *
+ * @since 9.0.0
+ */
+class CommentsEvent extends Event {
+	/**
+	 * @since 11.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_ADD = 'OCP\Comments\ICommentsManager::addComment';
+
+	/**
+	 * @since 11.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_PRE_UPDATE = 'OCP\Comments\ICommentsManager::preUpdateComment';
+
+	/**
+	 * @since 11.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_UPDATE = 'OCP\Comments\ICommentsManager::updateComment';
+
+	/**
+	 * @since 11.0.0
+	 * @deprecated 22.0.0
+	 */
+	public const EVENT_DELETE = 'OCP\Comments\ICommentsManager::deleteComment';
+
+	/** @var string */
+	protected $event;
+	/** @var IComment */
+	protected $comment;
+
+	/**
+	 * DispatcherEvent constructor.
+	 *
+	 * @param string $event
+	 * @param IComment $comment
+	 * @since 9.0.0
+	 */
+	public function __construct($event, IComment $comment) {
+		$this->event = $event;
+		$this->comment = $comment;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getEvent() {
+		return $this->event;
+	}
+
+	/**
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function getComment() {
+		return $this->comment;
+	}
+}
diff --git a/lib/public/Comments/IComment.php b/lib/public/Comments/IComment.php
new file mode 100644
index 00000000000..cdfcf188761
--- /dev/null
+++ b/lib/public/Comments/IComment.php
@@ -0,0 +1,314 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+/**
+ * Interface IComment
+ *
+ * This class represents a comment
+ *
+ * @since 9.0.0
+ */
+interface IComment {
+	/**
+	 * @since 9.0.0
+	 */
+	public const MAX_MESSAGE_LENGTH = 1000;
+
+	/**
+	 * returns the ID of the comment
+	 *
+	 * It may return an empty string, if the comment was not stored.
+	 * It is expected that the concrete Comment implementation gives an ID
+	 * by itself (e.g. after saving).
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getId();
+
+	/**
+	 * sets the ID of the comment and returns itself
+	 *
+	 * It is only allowed to set the ID only, if the current id is an empty
+	 * string (which means it is not stored in a database, storage or whatever
+	 * the concrete implementation does), or vice versa. Changing a given ID is
+	 * not permitted and must result in an IllegalIDChangeException.
+	 *
+	 * @param string $id
+	 * @return IComment
+	 * @throws IllegalIDChangeException
+	 * @since 9.0.0
+	 */
+	public function setId($id);
+
+	/**
+	 * returns the parent ID of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getParentId();
+
+	/**
+	 * sets the parent ID and returns itself
+	 * @param string $parentId
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setParentId($parentId);
+
+	/**
+	 * returns the topmost parent ID of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getTopmostParentId();
+
+
+	/**
+	 * sets the topmost parent ID and returns itself
+	 *
+	 * @param string $id
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setTopmostParentId($id);
+
+	/**
+	 * returns the number of children
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getChildrenCount();
+
+	/**
+	 * sets the number of children
+	 *
+	 * @param int $count
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setChildrenCount($count);
+
+	/**
+	 * returns the message of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMessage();
+
+	/**
+	 * sets the message of the comment and returns itself
+	 *
+	 * When the given message length exceeds MAX_MESSAGE_LENGTH an
+	 * MessageTooLongException shall be thrown.
+	 *
+	 * @param string $message
+	 * @param int $maxLength
+	 * @return IComment
+	 * @throws MessageTooLongException
+	 * @since 9.0.0 - $maxLength added in 16.0.2
+	 */
+	public function setMessage($message, $maxLength = self::MAX_MESSAGE_LENGTH);
+
+	/**
+	 * returns an array containing mentions that are included in the comment
+	 *
+	 * @return array each mention provides a 'type' and an 'id', see example below
+	 * @psalm-return list<array{type: 'guest'|'email'|'federated_group'|'group'|'federated_team'|'team'|'federated_user'|'user', id: non-empty-lowercase-string}>
+	 * @since 30.0.2 Type 'email' is supported
+	 * @since 29.0.0 Types 'federated_group', 'federated_team', 'team' and 'federated_user' are supported
+	 * @since 23.0.0 Type 'group' is supported
+	 * @since 17.0.0 Type 'guest' is supported
+	 * @since 11.0.0
+	 */
+	public function getMentions();
+
+	/**
+	 * returns the verb of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getVerb();
+
+	/**
+	 * sets the verb of the comment, e.g. 'comment' or 'like'
+	 *
+	 * @param string $verb
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setVerb($verb);
+
+	/**
+	 * returns the actor type
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getActorType();
+
+	/**
+	 * returns the actor ID
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getActorId();
+
+	/**
+	 * sets (overwrites) the actor type and id
+	 *
+	 * @param string $actorType e.g. 'users'
+	 * @param string $actorId e.g. 'zombie234'
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setActor($actorType, $actorId);
+
+	/**
+	 * returns the creation date of the comment.
+	 *
+	 * If not explicitly set, it shall default to the time of initialization.
+	 *
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	public function getCreationDateTime();
+
+	/**
+	 * sets the creation date of the comment and returns itself
+	 *
+	 * @param \DateTime $dateTime
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setCreationDateTime(\DateTime $dateTime);
+
+	/**
+	 * returns the date of the most recent child
+	 *
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	public function getLatestChildDateTime();
+
+	/**
+	 * sets the date of the most recent child
+	 *
+	 * @param \DateTime|null $dateTime
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setLatestChildDateTime(?\DateTime $dateTime = null);
+
+	/**
+	 * returns the object type the comment is attached to
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectType();
+
+	/**
+	 * returns the object id the comment is attached to
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectId();
+
+	/**
+	 * sets (overwrites) the object of the comment
+	 *
+	 * @param string $objectType e.g. 'files'
+	 * @param string $objectId e.g. '16435'
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setObject($objectType, $objectId);
+
+	/**
+	 * returns the reference id of the comment
+	 *
+	 * @return string|null
+	 * @since 19.0.0
+	 */
+	public function getReferenceId(): ?string;
+
+	/**
+	 * sets (overwrites) the reference id of the comment
+	 *
+	 * @param string|null $referenceId e.g. sha256 hash sum
+	 * @return IComment
+	 * @since 19.0.0
+	 */
+	public function setReferenceId(?string $referenceId): IComment;
+
+	/**
+	 * Returns the metadata of the comment
+	 *
+	 * @return array|null
+	 * @since 29.0.0
+	 */
+	public function getMetaData(): ?array;
+
+	/**
+	 * Sets (overwrites) the metadata of the comment
+	 * Data as a json encoded array
+	 *
+	 * @param array|null $metaData
+	 * @return IComment
+	 * @throws \JsonException When the metadata can not be converted to a json encoded string
+	 * @since 29.0.0
+	 */
+	public function setMetaData(?array $metaData): IComment;
+
+	/**
+	 * Returns the reactions array if exists
+	 *
+	 * The keys is the emoji of reaction and the value is the total.
+	 *
+	 * @return array<string, integer> e.g. ["👍":1]
+	 * @since 24.0.0
+	 */
+	public function getReactions(): array;
+
+	/**
+	 * Set summarized array of reactions by reaction type
+	 *
+	 * The keys is the emoji of reaction and the value is the total.
+	 *
+	 * @param array<string, integer>|null $reactions e.g. ["👍":1]
+	 * @return IComment
+	 * @since 24.0.0
+	 */
+	public function setReactions(?array $reactions): IComment;
+
+	/**
+	 * Set message expire date
+	 *
+	 * @param \DateTime|null $dateTime
+	 * @return IComment
+	 * @since 25.0.0
+	 */
+	public function setExpireDate(?\DateTime $dateTime): IComment;
+
+	/**
+	 * Get message expire date
+	 *
+	 * @return ?\DateTime
+	 * @since 25.0.0
+	 */
+	public function getExpireDate(): ?\DateTime;
+}
diff --git a/lib/public/Comments/ICommentsEventHandler.php b/lib/public/Comments/ICommentsEventHandler.php
new file mode 100644
index 00000000000..148ead2c367
--- /dev/null
+++ b/lib/public/Comments/ICommentsEventHandler.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Comments;
+
+/**
+ * Interface ICommentsEventHandler
+ *
+ * @since 11.0.0
+ * @deprecated 30.0.0 Register a listener for the CommentsEvent through the IEventDispatcher
+ */
+interface ICommentsEventHandler {
+	/**
+	 * @param CommentsEvent $event
+	 * @since 11.0.0
+	 * @deprecated 30.0.0 Register a listener for the CommentsEvent through the IEventDispatcher
+	 */
+	public function handle(CommentsEvent $event);
+}
diff --git a/lib/public/Comments/ICommentsManager.php b/lib/public/Comments/ICommentsManager.php
new file mode 100644
index 00000000000..7e59b5c7b06
--- /dev/null
+++ b/lib/public/Comments/ICommentsManager.php
@@ -0,0 +1,479 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+use OCP\IUser;
+use OCP\PreConditionNotMetException;
+
+/**
+ * Interface ICommentsManager
+ *
+ * This class manages the access to comments
+ *
+ * @since 9.0.0
+ */
+interface ICommentsManager {
+	/**
+	 * @const DELETED_USER type and id for a user that has been deleted
+	 * @see deleteReferencesOfActor
+	 * @since 9.0.0
+	 *
+	 * To be used as replacement for user type actors in deleteReferencesOfActor().
+	 *
+	 * User interfaces shall show "Deleted user" as display name, if needed.
+	 */
+	public const DELETED_USER = 'deleted_users';
+
+	/**
+	 * returns a comment instance
+	 *
+	 * @param string $id the ID of the comment
+	 * @return IComment
+	 * @throws NotFoundException
+	 * @since 9.0.0
+	 */
+	public function get($id);
+
+	/**
+	 * Returns the comment specified by the id and all it's child comments
+	 *
+	 * @param string $id
+	 * @param int $limit max number of entries to return, 0 returns all
+	 * @param int $offset the start entry
+	 * @return array{comment: IComment, replies: list<array{comment: IComment, replies: array<empty, empty>}>}
+	 * @since 9.0.0
+	 *
+	 * The return array looks like this
+	 * [
+	 * 	 'comment' => IComment, // root comment
+	 *   'replies' =>
+	 *   [
+	 *     0 =>
+	 *     [
+	 *       'comment' => IComment,
+	 *       'replies' =>
+	 *       [
+	 *         0 =>
+	 *         [
+	 *           'comment' => IComment,
+	 *           'replies' => [ … ]
+	 *         ],
+	 *         …
+	 *       ]
+	 *     ]
+	 *     1 =>
+	 *     [
+	 *       'comment' => IComment,
+	 *       'replies'=> [ … ]
+	 *     ],
+	 *     …
+	 *   ]
+	 * ]
+	 */
+	public function getTree($id, $limit = 0, $offset = 0);
+
+	/**
+	 * returns comments for a specific object (e.g. a file).
+	 *
+	 * The sort order is always newest to oldest.
+	 *
+	 * @param string $objectType the object type, e.g. 'files'
+	 * @param string $objectId the id of the object
+	 * @param int $limit optional, number of maximum comments to be returned. if
+	 *                   not specified, all comments are returned.
+	 * @param int $offset optional, starting point
+	 * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments
+	 *                                     that may be returned
+	 * @return list<IComment>
+	 * @since 9.0.0
+	 */
+	public function getForObject(
+		$objectType,
+		$objectId,
+		$limit = 0,
+		$offset = 0,
+		?\DateTime $notOlderThan = null,
+	);
+
+	/**
+	 * @param string $objectType the object type, e.g. 'files'
+	 * @param string $objectId the id of the object
+	 * @param int $lastKnownCommentId the last known comment (will be used as offset)
+	 * @param string $sortDirection direction of the comments (`asc` or `desc`)
+	 * @param int $limit optional, number of maximum comments to be returned. if
+	 *                   set to 0, all comments are returned.
+	 * @param bool $includeLastKnown
+	 * @param string $topmostParentId Limit the comments to a list of replies and its original root comment
+	 * @return list<IComment>
+	 * @since 14.0.0
+	 * @deprecated 24.0.0 - Use getCommentsWithVerbForObjectSinceComment instead
+	 */
+	public function getForObjectSince(
+		string $objectType,
+		string $objectId,
+		int $lastKnownCommentId,
+		string $sortDirection = 'asc',
+		int $limit = 30,
+		bool $includeLastKnown = false,
+		string $topmostParentId = '',
+	): array;
+
+	/**
+	 * @param string $objectType the object type, e.g. 'files'
+	 * @param string $objectId the id of the object
+	 * @param string[] $verbs List of verbs to filter by
+	 * @param int $lastKnownCommentId the last known comment (will be used as offset)
+	 * @param string $sortDirection direction of the comments (`asc` or `desc`)
+	 * @param int $limit optional, number of maximum comments to be returned. if
+	 *                   set to 0, all comments are returned.
+	 * @param bool $includeLastKnown
+	 * @param string $topmostParentId Limit the comments to a list of replies and its original root comment
+	 * @return list<IComment>
+	 * @since 24.0.0
+	 */
+	public function getCommentsWithVerbForObjectSinceComment(
+		string $objectType,
+		string $objectId,
+		array $verbs,
+		int $lastKnownCommentId,
+		string $sortDirection = 'asc',
+		int $limit = 30,
+		bool $includeLastKnown = false,
+		string $topmostParentId = '',
+	): array;
+
+	/**
+	 * Search for comments with a given content
+	 *
+	 * @param string $search content to search for
+	 * @param string $objectType Limit the search by object type
+	 * @param string $objectId Limit the search by object id
+	 * @param string $verb Limit the verb of the comment
+	 * @param int $offset
+	 * @param int $limit
+	 * @return list<IComment>
+	 * @since 14.0.0
+	 */
+	public function search(string $search, string $objectType, string $objectId, string $verb, int $offset, int $limit = 50): array;
+
+	/**
+	 * Search for comments on one or more objects with a given content
+	 *
+	 * @param string $search content to search for
+	 * @param string $objectType Limit the search by object type
+	 * @param array $objectIds Limit the search by object ids
+	 * @param string $verb Limit the verb of the comment
+	 * @param int $offset
+	 * @param int $limit
+	 * @return IComment[]
+	 * @since 21.0.0
+	 */
+	public function searchForObjects(string $search, string $objectType, array $objectIds, string $verb, int $offset, int $limit = 50): array;
+
+	/**
+	 * @param $objectType string the object type, e.g. 'files'
+	 * @param $objectId string the id of the object
+	 * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments
+	 *                                     that may be returned
+	 * @param string $verb Limit the verb of the comment - Added in 14.0.0
+	 * @return Int
+	 * @since 9.0.0
+	 */
+	public function getNumberOfCommentsForObject($objectType, $objectId, ?\DateTime $notOlderThan = null, $verb = '');
+
+	/**
+	 * @param string $objectType the object type, e.g. 'files'
+	 * @param string[] $objectIds the id of the object
+	 * @param IUser $user
+	 * @param string $verb Limit the verb of the comment - Added in 14.0.0
+	 * @return array Map with object id => # of unread comments
+	 * @psalm-return array<string, int>
+	 * @since 21.0.0
+	 */
+	public function getNumberOfUnreadCommentsForObjects(string $objectType, array $objectIds, IUser $user, $verb = ''): array;
+
+	/**
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param int $lastRead
+	 * @param string $verb
+	 * @return int
+	 * @since 21.0.0
+	 * @deprecated 24.0.0 - Use getNumberOfCommentsWithVerbsForObjectSinceComment instead
+	 */
+	public function getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, string $verb = ''): int;
+
+
+	/**
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param int $lastRead
+	 * @param string[] $verbs
+	 * @return int
+	 * @since 24.0.0
+	 */
+	public function getNumberOfCommentsWithVerbsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, array $verbs): int;
+
+	/**
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param \DateTime $beforeDate
+	 * @param string $verb
+	 * @return int
+	 * @since 21.0.0
+	 */
+	public function getLastCommentBeforeDate(string $objectType, string $objectId, \DateTime $beforeDate, string $verb = ''): int;
+
+	/**
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param string $verb
+	 * @param string $actorType
+	 * @param string[] $actors
+	 * @return \DateTime[] Map of "string actor" => "\DateTime most recent comment date"
+	 * @psalm-return array<string, \DateTime>
+	 * @since 21.0.0
+	 */
+	public function getLastCommentDateByActor(
+		string $objectType,
+		string $objectId,
+		string $verb,
+		string $actorType,
+		array $actors,
+	): array;
+
+	/**
+	 * Get the number of unread comments for all files in a folder
+	 *
+	 * @param int $folderId
+	 * @param IUser $user
+	 * @return array [$fileId => $unreadCount]
+	 * @since 12.0.0
+	 * @deprecated 29.0.0 use getNumberOfUnreadCommentsForObjects instead
+	 */
+	public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user);
+
+	/**
+	 * creates a new comment and returns it. At this point of time, it is not
+	 * saved in the used data storage. Use save() after setting other fields
+	 * of the comment (e.g. message or verb).
+	 *
+	 * @param string $actorType the actor type (e.g. 'users')
+	 * @param string $actorId a user id
+	 * @param string $objectType the object type the comment is attached to
+	 * @param string $objectId the object id the comment is attached to
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function create($actorType, $actorId, $objectType, $objectId);
+
+	/**
+	 * permanently deletes the comment specified by the ID
+	 *
+	 * When the comment has child comments, their parent ID will be changed to
+	 * the parent ID of the item that is to be deleted.
+	 *
+	 * @param string $id
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function delete($id);
+
+	/**
+	 * Get comment related with user reaction
+	 *
+	 * Throws PreConditionNotMetException when the system haven't the minimum requirements to
+	 * use reactions
+	 *
+	 * @param int $parentId
+	 * @param string $actorType
+	 * @param string $actorId
+	 * @param string $reaction
+	 * @return IComment
+	 * @throws NotFoundException
+	 * @throws PreConditionNotMetException
+	 * @since 24.0.0
+	 */
+	public function getReactionComment(int $parentId, string $actorType, string $actorId, string $reaction): IComment;
+
+	/**
+	 * Retrieve all reactions of a message
+	 *
+	 * Throws PreConditionNotMetException when the system haven't the minimum requirements to
+	 * use reactions
+	 *
+	 * @param int $parentId
+	 * @return IComment[]
+	 * @throws PreConditionNotMetException
+	 * @since 24.0.0
+	 */
+	public function retrieveAllReactions(int $parentId): array;
+
+	/**
+	 * Retrieve all reactions with specific reaction of a message
+	 *
+	 * Throws PreConditionNotMetException when the system haven't the minimum requirements to
+	 * use reactions
+	 *
+	 * @param int $parentId
+	 * @param string $reaction
+	 * @return IComment[]
+	 * @throws PreConditionNotMetException
+	 * @since 24.0.0
+	 */
+	public function retrieveAllReactionsWithSpecificReaction(int $parentId, string $reaction): array;
+
+	/**
+	 * Support reactions
+	 *
+	 * @return bool
+	 * @since 24.0.0
+	 */
+	public function supportReactions(): bool;
+
+	/**
+	 * saves the comment permanently
+	 *
+	 * if the supplied comment has an empty ID, a new entry comment will be
+	 * saved and the instance updated with the new ID.
+	 *
+	 * Otherwise, an existing comment will be updated.
+	 *
+	 * Throws NotFoundException when a comment that is to be updated does not
+	 * exist anymore at this point of time.
+	 *
+	 * @param IComment $comment
+	 * @return bool
+	 * @throws NotFoundException
+	 * @since 9.0.0
+	 */
+	public function save(IComment $comment);
+
+	/**
+	 * removes references to specific actor (e.g. on user delete) of a comment.
+	 * The comment itself must not get lost/deleted.
+	 *
+	 * A 'users' type actor (type and id) should get replaced by the
+	 * value of the DELETED_USER constant of this interface.
+	 *
+	 * @param string $actorType the actor type (e.g. 'users')
+	 * @param string $actorId a user id
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public function deleteReferencesOfActor($actorType, $actorId);
+
+	/**
+	 * deletes all comments made of a specific object (e.g. on file delete)
+	 *
+	 * @param string $objectType the object type (e.g. 'files')
+	 * @param string $objectId e.g. the file id
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public function deleteCommentsAtObject($objectType, $objectId);
+
+	/**
+	 * sets the read marker for a given file to the specified date for the
+	 * provided user
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param \DateTime $dateTime
+	 * @param \OCP\IUser $user
+	 * @since 9.0.0
+	 */
+	public function setReadMark($objectType, $objectId, \DateTime $dateTime, \OCP\IUser $user);
+
+	/**
+	 * returns the read marker for a given file to the specified date for the
+	 * provided user. It returns null, when the marker is not present, i.e.
+	 * no comments were marked as read.
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param \OCP\IUser $user
+	 * @return \DateTime|null
+	 * @since 9.0.0
+	 */
+	public function getReadMark($objectType, $objectId, \OCP\IUser $user);
+
+	/**
+	 * deletes the read markers for the specified user
+	 *
+	 * @param \OCP\IUser $user
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function deleteReadMarksFromUser(\OCP\IUser $user);
+
+	/**
+	 * deletes the read markers on the specified object
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function deleteReadMarksOnObject($objectType, $objectId);
+
+	/**
+	 * registers an Entity to the manager, so event notifications can be send
+	 * to consumers of the comments infrastructure
+	 *
+	 * @param \Closure $closure
+	 * @since 11.0.0
+	 */
+	public function registerEventHandler(\Closure $closure);
+
+	/**
+	 * registers a method that resolves an ID to a display name for a given type
+	 *
+	 * @param string $type
+	 * @param \Closure $closure
+	 * @throws \OutOfBoundsException
+	 * @since 11.0.0
+	 *
+	 * Only one resolver shall be registered per type. Otherwise a
+	 * \OutOfBoundsException has to thrown.
+	 */
+	public function registerDisplayNameResolver($type, \Closure $closure);
+
+	/**
+	 * resolves a given ID of a given Type to a display name.
+	 *
+	 * @param string $type
+	 * @param string $id
+	 * @return string
+	 * @throws \OutOfBoundsException
+	 * @since 11.0.0
+	 *
+	 * If a provided type was not registered, an \OutOfBoundsException shall
+	 * be thrown. It is upon the resolver discretion what to return of the
+	 * provided ID is unknown. It must be ensured that a string is returned.
+	 */
+	public function resolveDisplayName($type, $id);
+
+	/**
+	 * Load the Comments app into the page
+	 *
+	 * @since 21.0.0
+	 */
+	public function load(): void;
+
+	/**
+	 * Delete comments with field expire_date less than current date
+	 * Only will delete the message related with the object.
+	 *
+	 * @param string $objectType the object type (e.g. 'files')
+	 * @param string $objectId e.g. the file id, leave empty to expire on all objects of this type
+	 * @return boolean true if at least one row was deleted
+	 * @since 25.0.0
+	 */
+	public function deleteCommentsExpiredAtObject(string $objectType, string $objectId = ''): bool;
+}
diff --git a/lib/public/Comments/ICommentsManagerFactory.php b/lib/public/Comments/ICommentsManagerFactory.php
new file mode 100644
index 00000000000..bfe6154a48f
--- /dev/null
+++ b/lib/public/Comments/ICommentsManagerFactory.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+use OCP\IServerContainer;
+
+/**
+ * Interface ICommentsManagerFactory
+ *
+ * This class is responsible for instantiating and returning an ICommentsManager
+ * instance.
+ *
+ * @since 9.0.0
+ */
+interface ICommentsManagerFactory {
+	/**
+	 * Constructor for the comments manager factory
+	 *
+	 * @param IServerContainer $serverContainer server container
+	 * @since 9.0.0
+	 */
+	public function __construct(IServerContainer $serverContainer);
+
+	/**
+	 * creates and returns an instance of the ICommentsManager
+	 *
+	 * @return ICommentsManager
+	 * @since 9.0.0
+	 */
+	public function getManager();
+}
diff --git a/lib/public/Comments/IllegalIDChangeException.php b/lib/public/Comments/IllegalIDChangeException.php
new file mode 100644
index 00000000000..08eddfc6fa4
--- /dev/null
+++ b/lib/public/Comments/IllegalIDChangeException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception for illegal attempts to modify a comment ID
+ * @since 9.0.0
+ */
+class IllegalIDChangeException extends \Exception {
+}
diff --git a/lib/public/Comments/MessageTooLongException.php b/lib/public/Comments/MessageTooLongException.php
new file mode 100644
index 00000000000..4358dc2e291
--- /dev/null
+++ b/lib/public/Comments/MessageTooLongException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception thrown when a comment message exceeds the allowed character limit
+ * @since 9.0.0
+ */
+class MessageTooLongException extends \OverflowException {
+}
diff --git a/lib/public/Comments/NotFoundException.php b/lib/public/Comments/NotFoundException.php
new file mode 100644
index 00000000000..4f25fdbf09f
--- /dev/null
+++ b/lib/public/Comments/NotFoundException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception for not found entity
+ * @since 9.0.0
+ */
+class NotFoundException extends \Exception {
+}