Add documentation to the repository

2 files changed, 260 insertions, 0 deletions

diff --git a/docs/notification-workflow.md b/docs/notification-workflow.md
new file mode 100644
index 0000000..bf06fa0
--- /dev/null
+++ b/docs/notification-workflow.md
@@ -0,0 +1,143 @@
+# Notification Workflow as an App that sends Notifications
+
+## Example story
+
+Let's assume the following example scenario. Our app is the files_sharing app. We want
+to notify the user when a remote share has to be accepted/decline. If the user has dealt
+with it, we want to remove the notification again.
+
+### Creating a new Notification
+
+  1. Grab a new notification object (`\OCP\Notification\INotification`) from the manager
+  (`\OCP\Notification\IManager`):
+    ```php
+    $manager = \OC::$server->getNotificationManager();
+    $notification = $manager->createNotification();
+    ```
+
+  2. Set the necessary information for the notification:
+    ```php
+    $acceptAction = $notification->createAction();
+    $acceptAction->setLabel('accept')
+        ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'POST');
+
+    $declineAction = $notification->createAction();
+    $declineAction->setLabel('decline')
+        ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'DELETE');
+
+    $notification->setApp('files_sharing')
+        ->setUser('recipient1')
+        ->setDateTime(new DateTime())
+        ->setObject('remote', '1337') // $type and $id
+        ->setSubject('remote_share', ['/fancyFolder']) // $subject and $parameters
+        ->addAction($acceptAction)
+        ->addAction($declineAction)
+    ;
+    ```
+  Setting **app, user, timestamp, object and subject** are mandatory. You should not use a
+  translated subject, message or action label. Use something like a "language key", to avoid
+  length problems with translations in the storage of a notification app. Translation is done
+  via invocation of your notifier by the manager when the notification is prepared for display.
+
+  3. Send the notification back to the manager:
+    ```php
+    $manager->notify($notification);
+    ```
+
+### Preparing a notification for display
+
+  1. In `app.php` register your Notifier (`\OCP\Notification\INotifier`) interface to the manager,
+  using a `\Closure`:
+    ```php
+    $manager = \OC::$server->getNotificationManager();
+    $manager->registerNotifier(function() {
+        return new \OCA\Files_Sharing\Notifier(
+            \OC::$server->getL10NFactory()
+        );
+    });
+    ```
+
+  2. The manager will execute the closure and then call the `prepare()` method on your notifier.
+  If the notification is not known by your app, just throw an `\InvalidArgumentException`,
+  but if it is actually from your app, you must set the parsed subject, message and action labels:
+    ```php
+    protected $factory;
+
+    public function __construct(\OCP\L10N\IFactory $factory) {
+        $this->factory = $factory;
+    }
+
+    /**
+     * @param INotification $notification
+     * @param string $languageCode The code of the language that should be used to prepare the notification
+     */
+    public function prepare(INotification $notification, $languageCode) {
+        if ($notification->getApp() !== 'files_sharing') {
+            // Not my app => throw
+            throw new \InvalidArgumentException();
+        }
+
+        // Read the language from the notification
+        $l = $this->factory->get('myapp', $languageCode);
+
+        switch ($notification->getSubject()) {
+            // Deal with known subjects
+            case 'remote_share':
+                $notification->setParsedSubject(
+                    (string) $l->t('You received the remote share "%s"', $notification->getSubjectParameters())
+                );
+                
+                // Deal with the actions for a known subject
+                foreach ($notification->getActions() as $action) {
+                    switch ($action->getLabel()) {
+                        case 'accept':
+                            $action->setParsedLabel(
+                                (string) $l->t('Accept')
+                            );
+                        break;
+ 
+                        case 'decline':
+                            $action->setParsedLabel(
+                                (string) $l->t('Decline')
+                            );
+                        break;
+                    }
+
+                    $notification->addParsedAction($action);
+                }
+                return $notification;
+            break;
+
+            default:
+                // Unknown subject => Unknown notification => throw
+                throw new \InvalidArgumentException();
+        }
+    }
+    ```
+
+### Marking a notification as read/deleted/processed/obsoleted
+
+Now in case the user accepted the share or the share was removed/unshared, we want to remove
+the notification, because no user action is needed anymore. To do this, we simply have to
+call the `markProcessed()` method on the manager with the neccessary information on a
+notification object:
+
+```php
+$manager = \OC::$server->getNotificationManager();
+$notification->setApp('files_sharing')
+    ->setObject('remote', 1337)
+    ->setUser('recipient1');
+$manager->markProcessed($notification);
+```
+
+Thereby only the app name is mandatory: so if you don't set the user, the notification
+will be marked as processed for all users that have it. So the following example will
+remove all notifications for the app files_sharing on the object "remote #1337":
+
+```php
+$manager = \OC::$server->getNotificationManager();
+$notification->setApp('files_sharing')
+    ->setObject('remote', 1337);
+$manager->markProcessed($notification);
+```
+
diff --git a/docs/ocs-endpoint-v1.md b/docs/ocs-endpoint-v1.md
new file mode 100644
index 0000000..f456feb
--- /dev/null
+++ b/docs/ocs-endpoint-v1.md
@@ -0,0 +1,117 @@
+# Reading and deleting notifications as a Client
+
+## Checking the capabilities of the server
+
+In order to find out if notifications is installed/enabled on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
+
+```json
+{
+  "ocs": {
+    ...
+    "data": {
+      ...
+      "capabilities": {
+        ...
+        "notifications": {
+          "ocs-endpoints": [
+            "list",
+            "get",
+            "delete"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+
+## Getting the notifications of a user
+
+The user needs to be identified/logged in by the server. Then you can just run a simple GET request against `/ocs/v2.php/apps/notifications/api/v1/notifications` to grab a list of notifications:
+
+```json
+{
+  "ocs": {
+    "meta": {
+      "status": "ok",
+      "statuscode": 200,
+      "message": null
+    },
+    "data": [
+      {
+        "notification_id": 61,
+        "app": "files_sharing",
+        "user": "admin",
+        "datetime": "2004-02-12T15:19:21+00:00",
+        "object_type": "remote_share",
+        "object_id": "13",
+        "subject": "You received admin@localhost as a remote share from test",
+        "message": "",
+        "link": "http://localhost/index.php/apps/files_sharing/pending",
+        "actions": [
+          {
+            "label": "Accept",
+            "link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
+            "type": "POST",
+            "primary": true
+          },
+          {
+            "label": "Decline",
+            "link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
+            "type": "DELETE",
+            "primary": false
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note:** In case the Request return status code `204` (No content), you can slow down the polling to once per hour. This status code means that there is no app, that can generate notifications.
+
+### Specification
+
+Optional elements are still set in the array, the value is just empty:
+
+Type | Empty value
+---- | -----------
+string | `""`
+array | `[]`
+
+#### Notification Element
+
+Field name | Type | Value description
+---------- | ---- | -----------------
+notification_id | int | Unique identifier of the notification, can be used to dismiss a notification
+app | string | Name of the app that triggered the notification
+user | string | User id of the user that receives the notification
+datetime | string | ISO 8601 date and time when the notification was published
+object_type | string | Type of the object the notification is about, that can be used in php to mark a notification as resolved
+object_id | string | Type of the object the notification is about, that can be used in php to mark a notification as resolved
+subject | string | Translated short subject that should be presented to the user
+message | string | (Optional) Translated potentially longer message that should be presented to the user
+link | string | (Optional) A link that should be followed when the subject/message is clicked
+actions | array | (Optional) An array of action elements
+
+
+#### Action Element
+
+Field name | Type | Value description
+---------- | ---- | -----------------
+label | string | Translated short label of the action/button that should be presented to the user
+link | string | A link that should be followed when the action is performed/clicked
+type | string | HTTP method that should be used for the request against the link: GET, POST, DELETE
+primary | bool | If the action is the primary action for the notification or not
+
+
+## Get a single notification for a user
+
+In order to get a single notification, you can send a GET request against `/ocs/v2.php/apps/notifications/api/v1/notifications/{id}`
+
+
+## Deleting a notification for a user
+
+In order to delete a notification, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v1/notifications/{id}`
+