feat(developer): document the new out-of-office feature

Signed-off-by: Richard Steinmetz <richard@steinmetz.cloud>

developer_manual/client_apis/OCS/index.rst

@@ -20,3 +20,4 @@ The old documentation is still kept as it provides some additional documentation
    ocs-translation-api
    ocs-textprocessing-api
    ocs-text2image-api
+   ocs-out-of-office-api

developer_manual/client_apis/OCS/ocs-out-of-office-api.rst

@@ -0,0 +1,130 @@
+.. _ocs-out-of-office-api:
+
+=====================
+OCS Out-of-office API
+=====================
+
+.. versionadded:: 28.0
+
+The OCS Out-of-office API allows you to access and modify out-of-office data of users.
+
+The base URL for all calls to the share API is:
+*<nextcloud_base_url>/ocs/v2.php/apps/dav/api/v1/outOfOffice*
+
+All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
+
+
+Fetch ongoing data
+------------------
+
+Fetch data of the ongoing out-of-office period of a user.
+
+* Method: ``GET``
+* Endpoint: ``/{userId}``
+* Response:
+    - Status code:
+        + ``200 OK`` Out-of-office data
+        + ``404 Not Found`` If the user does not have an ongoing out-of-office period
+    - Data (is only sent if the status code is ``200 OK``):
+
++--------------+--------+---------------------------------------------------------------------+
+| field        | type   | Description                                                         |
++--------------+--------+---------------------------------------------------------------------+
+| ``id``       | int    | Database ID of the absence data entity                              |
++--------------+--------+---------------------------------------------------------------------+
+| ``userId``   | string | ID of the user which the data belongs to                            |
++--------------+--------+---------------------------------------------------------------------+
+| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD``                   |
++--------------+--------+---------------------------------------------------------------------+
+| ``lastDay``  | string | Last day of the absence in format ``YYYY-MM-DD``                    |
++--------------+--------+---------------------------------------------------------------------+
+| ``status``   | string | Short text that is set as user status during the absence            |
++--------------+--------+---------------------------------------------------------------------+
+| ``message``  | string | Longer multiline message that is shown to others during the absence |
++--------------+--------+---------------------------------------------------------------------+
+
+Fetch upcoming or ongoing data
+------------------------------
+
+The returned out-of-office period might not have started yet. This endpoint will return data of the
+ongoing or next upcoming out-of-office period of a user.
+
+* Method: ``GET``
+* Endpoint: ``/{userId}``
+* Response:
+    - Status code:
+        + ``200 OK`` Out-of-office data
+        + ``404 Not Found`` If the user did not schedule an out-of-office period
+    - Data (is only sent if the status code is ``200 OK``):
+
++--------------+--------+---------------------------------------------------------------------+
+| field        | type   | Description                                                         |
++--------------+--------+---------------------------------------------------------------------+
+| ``id``       | int    | Database ID of the absence data entity                              |
++--------------+--------+---------------------------------------------------------------------+
+| ``userId``   | string | ID of the user which the data belongs to                            |
++--------------+--------+---------------------------------------------------------------------+
+| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD``                   |
++--------------+--------+---------------------------------------------------------------------+
+| ``lastDay``  | string | Last day of the absence in format ``YYYY-MM-DD``                    |
++--------------+--------+---------------------------------------------------------------------+
+| ``status``   | string | Short text that is set as user status during the absence            |
++--------------+--------+---------------------------------------------------------------------+
+| ``message``  | string | Longer multiline message that is shown to others during the absence |
++--------------+--------+---------------------------------------------------------------------+
+
+Modify out-of-office data
+-------------------------
+
+It is only possible to modify out-of-office data of the currently logged in user.
+
+* Method: ``POST``
+* Endpoint: ``/``
+* Data:
+
++--------------+--------+---------------------------------------------------------------------+
+| field        | type   | Description                                                         |
++--------------+--------+---------------------------------------------------------------------+
+| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD``                   |
++--------------+--------+---------------------------------------------------------------------+
+| ``lastDay``  | string | Last day of the absence in format ``YYYY-MM-DD``                    |
++--------------+--------+---------------------------------------------------------------------+
+| ``status``   | string | Short text that is set as user status during the absence            |
++--------------+--------+---------------------------------------------------------------------+
+| ``message``  | string | Longer multiline message that is shown to others during the absence |
++--------------+--------+---------------------------------------------------------------------+
+
+* Response:
+    - Status code:
+        + ``200 OK`` Updated out-of-office data
+        + ``400 Bad Request`` If the first day is not before the last day
+        + ``401 Unauthorized`` If the user is not logged in
+    - Data (is only sent if the status code is ``200 OK``):
+
++--------------+--------+---------------------------------------------------------------------+
+| field        | type   | Description                                                         |
++--------------+--------+---------------------------------------------------------------------+
+| ``id``       | int    | Database ID of the absence data entity                              |
++--------------+--------+---------------------------------------------------------------------+
+| ``userId``   | string | ID of the user which the data belongs to                            |
++--------------+--------+---------------------------------------------------------------------+
+| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD``                   |
++--------------+--------+---------------------------------------------------------------------+
+| ``lastDay``  | string | Last day of the absence in format ``YYYY-MM-DD``                    |
++--------------+--------+---------------------------------------------------------------------+
+| ``status``   | string | Short text that is set as user status during the absence            |
++--------------+--------+---------------------------------------------------------------------+
+| ``message``  | string | Longer multiline message that is shown to others during the absence |
++--------------+--------+---------------------------------------------------------------------+
+
+Clear data and disable out-of-office
+------------------------------------
+
+It is only possible to clear out-of-office data of the currently logged in user.
+
+* Method: ``DELETE``
+* Endpoint: ``/``
+* Response:
+    - Status code:
+        + ``200 OK`` Out-of-office data was cleared
+        + ``401 Unauthorized`` If the user is not logged in

developer_manual/digging_deeper/index.rst

@@ -43,3 +43,4 @@ Digging deeper
    profiler
    deadlock
    phonenumberutil
+   out_of_office

developer_manual/digging_deeper/out_of_office.rst

@@ -0,0 +1,118 @@
+=====================
+Out-of-office periods
+=====================
+
+.. versionadded:: 28.0
+
+Since Nextcloud 28, users may set their out-of-office periods in their personal settings. The data
+can be accessed and modified by Nextcloud Apps via OCP and by clients via OCS. Nextcloud Apps can
+also listen to events emitted by the out-of-office feature.
+
+The OCS API is documented in the :ref:`client section<ocs-out-of-office-api>`.
+
+Access data from within a Nextcloud App via OCP
+-------------------------------------------------
+
+The out-of-office data can be accessed through the `OCP\\User\\IAvailabilityCoordinator`
+interface. It provides the following methods:
+
+.. code-block:: php
+
+	/**
+	 * Check if the feature is enabled on this instance
+	 */
+	public function isEnabled(): bool;
+
+.. code-block:: php
+
+	/**
+	 * Get the user's ongoing out-of-office data, if any
+	 */
+	public function getCurrentOutOfOfficeData(IUser $user): ?IOutOfOfficeData;
+
+.. code-block:: php
+
+	/**
+	 * Reset the absence cache to null
+	 */
+	public function clearCache(string $userId): void;
+
+.. code-block:: php
+
+	/**
+	 * Is the absence in effect at this moment
+	 */
+	public function isInEffect(IOutOfOfficeData $data): bool;
+
+Listening to events
+-------------------
+
+All events have one common method to retrieve data about the  affected out-of-office period.
+
+.. code-block:: php
+
+	public function getData(): IOutOfOfficeData;
+
+
+The following events are emitted by the out-of-office feature:
+
+* ``OCP\User\Events\OutOfOfficeScheduledEvent`` If a new out-of-office period is scheduled for a
+  user. This event is only emitted once when there was no out-of-office period before.
+* ``OCP\User\Events\OutOfOfficeChangedEvent`` If the out-of-office data of a user is changed.
+* ``OCP\User\Events\OutOfOfficeDeletedEvent`` If the out-of-office period of a user is deleted.
+* ``OCP\User\Events\OutOfOfficeStartedEvent`` If an out-of-office period starts. This event is only
+  emitted once and not if a period starting in the past is created.
+* ``OCP\User\Events\OutOfOfficeEndedEvent`` If an out-of-office period ends. This event is only
+  emitted once and not if a period ending in the past is created.
+
+Common data structure
+---------------------
+
+The OCP API and emitted events share a common data structure `OCP\\User\\IOutOfOfficeData`. The
+start and end dates are represented as UNIX timestamps.
+
+.. code-block:: php
+
+    interface IOutOfOfficeData extends JsonSerializable {
+        /**
+         * Get the unique token assigned to the current out-of-office event
+         */
+        public function getId(): string;
+
+        public function getUser(): IUser;
+
+        /**
+         * Get the accurate out-of-office start date
+         *
+         * This event is not guaranteed to be emitted exactly at start date
+         */
+        public function getStartDate(): int;
+
+        /**
+         * Get the (preliminary) out-of-office end date
+         */
+        public function getEndDate(): int;
+
+        /**
+         * Get the short summary text displayed in the user status and similar
+         */
+        public function getShortMessage(): string;
+
+        /**
+         * Get the long out-of-office message for auto responders and similar
+         */
+        public function getMessage(): string;
+    }
+
+It can be serialized to a JSON object with the following structure:
+
+.. code-block::
+
+    {
+        id: string,
+        userId: string,
+        startDate: int,
+        endDate: int,
+        shortMessage: string,
+        message: string,
+    }