api docs: Document PATCH /settings/notifications.

With significant tweaks by tabbott after rebasing.

templates/zerver/api/update-notification-settings.md

@@ -0,0 +1,52 @@
+# Update notification settings
+
+This endpoint is used to edit the user's global notification settings.
+See [this endpoint](/api/update-subscription-properties) for
+per-stream notification settings.
+
+`PATCH {{ api_url }}/v1/settings/notifications`
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/settings/notifications:patch|example}
+
+{tab|curl}
+``` curl
+curl -X PATCH {{ api_url }}/v1/settings/notifications \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d "enable_stream_desktop_notifications=true" \
+    -d "enable_stream_email_notifications=true" \
+    -d "enable_stream_push_notifications=true" \
+    -d "enable_stream_sounds=true" \
+    -d "enable_desktop_notifications=true" \
+    -d "enable_sounds=true" \
+    -d "enable_offline_email_notifications=true" \
+    -d "enable_offline_push_notifications=true" \
+    -d "enable_online_push_notifications=true" \
+    -d "enable_digest_emails=true" \
+    -d "message_content_in_email_notifications=true"
+```
+
+{end_tabs}
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/settings/notifications:patch}
+
+## Response
+
+#### Return values
+
+The server will return the settings that have been changed after the request,
+with their new value. Please note that this doesn't necessarily mean that it
+will return all the settings passed as parameters in the request, but only
+those ones that were different than the already existing setting.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/settings/notifications:patch|fixture(200)}

templates/zerver/help/include/rest-endpoints.md

@@ -32,6 +32,7 @@
 * [Set "typing" status](/api/typing)
 * [Get user presence](/api/get-presence)
 * [Get all user groups](/api/get-user-groups)
+* [Update notification settings](/api/update-notification-settings)
 
 #### Server & organizations
 

zerver/lib/api_test_helpers.py

@@ -762,6 +762,20 @@ def get_server_settings(client):
 
     validate_against_openapi_schema(result, '/server_settings', 'get', '200')
 
+def update_notification_settings(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Enable push notifications even when online
+    request = {
+        'enable_offline_push_notifications': True,
+        'enable_online_push_notifications': True,
+    }
+    result = client.update_notification_settings(request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/settings/notifications', 'patch', '200')
+
 def upload_file(client):
     # type: (Client) -> None
     path_to_file = os.path.join(ZULIP_DIR, 'zerver', 'tests', 'images', 'img.jpg')
@@ -896,17 +910,6 @@ def update_user_group_members(client, group_id):
 
     assert result['result'] == 'success'
 
-def update_notification_settings(client):
-    # type: (Client) -> None
-    request = {
-        'enable_stream_push_notifications': True,
-        'enable_offline_push_notifications': False
-    }
-
-    result = client.update_notification_settings(request)
-
-    assert result['result'] == 'success'
-
 def test_invalid_api_key(client_with_invalid_key):
     # type: (Client) -> None
     result = client_with_invalid_key.list_subscriptions()
@@ -951,7 +954,6 @@ TEST_FUNCTIONS = {
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
     '/users/me/subscriptions/properties:post': update_subscription_settings,
-    '/settings/notifications:patch': update_notification_settings,
     '/users:get': get_members,
     '/realm/emoji:get': get_realm_emoji,
     '/realm/emoji/<emoji_name>:post': upload_custom_emoji,
@@ -961,6 +963,7 @@ TEST_FUNCTIONS = {
     '/register:post': register_queue,
     '/events:delete': deregister_queue,
     '/server_settings:get': get_server_settings,
+    '/settings/notifications:patch': update_notification_settings,
     '/user_uploads:post': upload_file,
     '/users/me/{stream_id}/topics:get': get_stream_topics,
     '/typing:post': set_typing_status,
@@ -1050,6 +1053,7 @@ def test_users(client):
     create_user(client)
     get_members(client)
     get_profile(client)
+    update_notification_settings(client)
     upload_file(client)
     set_typing_status(client)
     get_user_presence(client)

zerver/openapi/zulip.yaml

@@ -1783,6 +1783,148 @@ paths:
                         "result": "success",
                         "require_email_format_usernames": true
                     }
+  /settings/notifications:
+    patch:
+      description: Modify the user's preferences for notifications.
+      parameters:
+      - name: enable_stream_desktop_notifications
+        in: query
+        description: Enable visual desktop notifications for stream messages.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_stream_email_notifications
+        in: query
+        description: Enable email notifications for stream messages.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_stream_push_notifications
+        in: query
+        description: Enable mobile notifications for stream messages.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_stream_audible_notifications
+        in: query
+        description: Enable audible desktop notifications for stream messages.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_desktop_notifications
+        in: query
+        description: Enable visual desktop notifications for private messages
+          and @-mentions.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_sounds
+        in: query
+        description: Enable audible desktop notifications for private messages
+          and @-mentions.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_offline_email_notifications
+        in: query
+        description: Enable email notifications for private messages and
+          @-mentions received when the user is offline.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_offline_push_notifications
+        in: query
+        description: Enable mobile notification for private messages and
+          @-mentions received when the user is offline.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_online_push_notifications
+        in: query
+        description: Enable mobile notification for private messages and
+          @-mentions received when the user is online.
+        schema:
+          type: boolean
+        example: true
+      - name: enable_digest_emails
+        in: query
+        description: Enable digest emails when the user is away.
+        schema:
+          type: boolean
+        example: true
+      - name: message_content_in_email_notifications
+        in: query
+        description: Include the message's content in missed messages email
+          notifications.
+        schema:
+          type: boolean
+        example: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    enable_desktop_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_desktop_notifications`, if it was changed in
+                        this request.
+                    enable_digest_emails:
+                      type: boolean
+                      description: The setting for `enable_digest_emails`, if
+                        it was changed in this request.
+                    enable_offline_email_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_offline_email_notifications`, if it was changed
+                        in this request.
+                    enable_offline_push_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_offline_push_notifications`, if it was changed
+                        in this request.
+                    enable_online_push_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_online_push_notifications`, if it was changed
+                        in this request.
+                    enable_sounds:
+                      type: boolean
+                      description: The setting for `enable_sounds`, if it was
+                        changed in this request.
+                    enable_stream_email_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_stream_email_notifications`, if it was changed
+                        in this request.
+                    enable_stream_push_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_stream_push_notifications`, if it was changed
+                        in this request.
+                    enable_stream_audible_notifications:
+                      type: boolean
+                      description: The setting for
+                        `enable_stream_audible_notifications`, if it was changed in this
+                        request.
+                    message_content_in_email_notifications:
+                      type: boolean
+                      description: The setting for
+                        `message_content_in_email_notifications`, if it was
+                        changed in this request.
+                - example:
+                    {
+                        "enable_offline_push_notifications": true,
+                        "enable_online_push_notifications": true,
+                        "msg": "",
+                        "result": "success"
+                    }
   /streams:
     get:
       description: Get all streams that the user has access to.