@myronsi/messenger-api 2.1.0-alpha.1 → 2.1.0-alpha.10

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.1.0-alpha.1
+  version: 2.1.0-alpha.10
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -444,6 +444,33 @@ paths:
         "400": { $ref: "#/components/responses/BadRequest" }
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
+  /me/avatars/{avatar_id}:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+      - name: avatar_id
+        in: path
+        required: true
+        description: "`id` of an `AvatarVersion` of the caller."
+        schema: { $ref: "#/components/schemas/Id" }
+    delete:
+      tags: [me]
+      operationId: deleteMyAvatar
+      summary: Delete one of your avatars
+      description: |
+        Removes the avatar from your history. When it is the current one, the newest remaining avatar becomes
+        current again; without one you get the default avatar. The image is deleted from storage once nothing
+        uses it any more.
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "200":
+          description: Updated user
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Me" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "404": { $ref: "#/components/responses/NotFound" }
   /me/password:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -670,7 +697,7 @@ paths:
         required: true
         schema:
           type: string
-          enum: [avatar_visibility, profile_visibility, presence_visibility, group_invites]
+          enum: [avatar_visibility, profile_visibility, presence_visibility, group_invites, direct_messages, search_visibility]
       - name: effect
         in: path
         required: true
@@ -780,6 +807,10 @@ paths:
       tags: [users]
       operationId: getUserByUsername
       summary: Profile by username
+      description: |
+        Like `GET /users/{user_id}`: a user whose `search_visibility` hides them from the current user (`nobody`
+        without an `allow` exception, or a `deny` exception) is `404` unless the two share a chat. Lookups are
+        rate limited per user.
       parameters:
         - name: username
           in: path
@@ -795,6 +826,7 @@ paths:
               schema: { $ref: "#/components/schemas/User" }
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
   /users/{user_id}:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -804,6 +836,10 @@ paths:
       tags: [users]
       operationId: getUser
       summary: Profile by ID
+      description: |
+        A user whose `search_visibility` hides them from the current user (`nobody` without an `allow` exception,
+        or a `deny` exception) is `404` unless the two share a chat. Your own profile is always found. Lookups are
+        rate limited per user.
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -814,6 +850,7 @@ paths:
               schema: { $ref: "#/components/schemas/User" }
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
   /users/{user_id}/avatar:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -825,12 +862,18 @@ paths:
       summary: Current avatar image
       description: |
         Respects the avatar visibility of the user; falls back to the default avatar. With `version`, an
-        earlier avatar of the history (`AvatarVersion.url`).
+        earlier avatar of the history (`AvatarVersion.url`). `avatar_url` carries `rev`, the revision of the
+        current avatar: while it matches, the answer may be cached for a year (`immutable`), because a new
+        avatar gets a new `rev` and so a new URL.
       parameters:
         - name: version
           in: query
           description: "`id` of an `AvatarVersion` of this user."
           schema: { $ref: "#/components/schemas/Id" }
+        - name: rev
+          in: query
+          description: Revision of the current avatar, as given in `avatar_url`.
+          schema: { type: string, maxLength: 64 }
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -888,6 +931,9 @@ paths:
       tags: [users]
       operationId: setContactName
       summary: Set your own display name for a user
+      description: |
+        Follows the rules of `GET /users/{user_id}`: a user whose `search_visibility` hides them from you is `404`
+        unless the two of you share a chat, and the calls count against the same per-user limit.
       requestBody:
         required: true
         content:
@@ -904,6 +950,7 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
         "422": { $ref: "#/components/responses/ValidationFailed" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
     delete:
       tags: [users]
       operationId: removeContactName
@@ -1281,7 +1328,8 @@ paths:
     patch:
       tags: [messages]
       operationId: editMessage
-      summary: Edit your text message
+      summary: Edit your text message or the caption of your file
+      description: An empty `content` removes the caption of a file message; a text message needs at least one character.
       requestBody:
         required: true
         content:
@@ -1355,6 +1403,70 @@ paths:
         "404": { $ref: "#/components/responses/NotFound" }
         "422": { $ref: "#/components/responses/ValidationFailed" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
+  /chats/{chat_id}/messages/forward:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+      - $ref: "#/components/parameters/ChatId"
+    post:
+      tags: [messages]
+      operationId: forwardMessages
+      summary: Forward several messages of a chat to other chats
+      description: |
+        Copies up to 20 messages of the chat, oldest first, into every target chat, at most 20 copies in all. Every
+        copy counts against the sender's message rate. Every message and target is checked before anything is
+        written, so a refused one forwards nothing.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ForwardMessagesRequest" }
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "201":
+          description: The new messages, per target chat oldest first
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: "#/components/schemas/Message" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+  /chats/{chat_id}/messages/delete:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+      - $ref: "#/components/parameters/ChatId"
+    post:
+      tags: [messages]
+      operationId: deleteMessages
+      summary: Delete several messages of a chat
+      description: |
+        Deletes up to 100 messages of the chat with the rules of `DELETE /messages/{message_id}`. Every message
+        is checked first: when one may not be deleted, none is. With `scope` everyone, messages that are already
+        deleted for everyone count as done, so a retry after a partial failure finishes the rest.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DeleteMessagesRequest" }
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "204":
+          description: Deleted
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
 
   # -------------------------------------------------------------- search
   /search/messages:
@@ -1715,6 +1827,212 @@ paths:
         "404": { $ref: "#/components/responses/NotFound" }
         "409": { $ref: "#/components/responses/Conflict" }
 
+  /me/notifications:
+    get:
+      tags:
+        - me
+      operationId: getNotificationSettings
+      summary: Notification preferences and supported push platforms
+      responses:
+        "200":
+          description: Notification settings or registered device
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NotificationSettings"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+    put:
+      tags:
+        - me
+      operationId: updateNotificationSettings
+      summary: Replace notification preferences
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NotificationPreferences"
+      responses:
+        "204":
+          description: Saved
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /notifications/avatar/{token}:
+    parameters:
+      - name: token
+        in: path
+        required: true
+        description: "`avatar_token` of a push notification."
+        schema: { type: string, maxLength: 256 }
+    get:
+      tags: [me]
+      operationId: getNotificationAvatar
+      summary: Sender avatar for a push notification
+      description: |
+        For the service worker, which has no session: the token in the push payload names the recipient
+        and the sender and expires after an hour. Follows the sender's avatar visibility for the recipient.
+      security: []
+      responses:
+        "200":
+          description: Image
+          content:
+            image/*:
+              schema: { type: string, format: binary }
+        "206":
+          description: The requested byte range (`Range` header)
+          content:
+            image/*:
+              schema: { type: string, format: binary }
+        "302":
+          description: Redirect to a short-lived signed storage URL (with `MEDIA_SIGNED_URLS`)
+        "304":
+          description: Not modified (`If-None-Match` with the `ETag` of an earlier answer)
+        "416":
+          description: The requested range is outside the file
+        "404": { $ref: "#/components/responses/NotFound" }
+  /notifications/read/{token}:
+    parameters:
+      - name: token
+        in: path
+        required: true
+        description: "`read_token` of a push notification."
+        schema: { type: string, maxLength: 256 }
+    post:
+      tags: [me]
+      operationId: markNotificationRead
+      summary: Mark a chat read from a push notification
+      description: |
+        For the notification's "Mark as read" action: marks the chat read up to the notified message for
+        the recipient the token names. The token expires after seven days.
+      security: []
+      responses:
+        "204":
+          description: Marked as read
+        "404": { $ref: "#/components/responses/NotFound" }
+  /me/notification-devices:
+    post:
+      tags:
+        - me
+      operationId: registerNotificationDevice
+      summary: Register a push destination for the current session
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NotificationDeviceRequest"
+      responses:
+        "200":
+          description: Notification settings or registered device
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NotificationDeviceRegistered"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /me/notification-devices/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    delete:
+      tags:
+        - me
+      operationId: deleteNotificationDevice
+      summary: Unregister a push destination for the current session
+      responses:
+        "204":
+          description: Saved
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /chats/{chatId}/notification-mute:
+    parameters:
+      - name: chatId
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/Id"
+    put:
+      tags:
+        - me
+      operationId: setNotificationMute
+      summary: Mute or unmute a chat
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NotificationMuteRequest"
+      responses:
+        "204":
+          description: Saved
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /me/notification-devices/{id}/activity:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    put:
+      tags:
+        - me
+      operationId: updateNotificationActivity
+      summary: Report a visible client with a healthy live connection
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NotificationActivity"
+      responses:
+        "204":
+          description: Saved
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+
 components:
   securitySchemes:
     bearerAuth:
@@ -1845,6 +2163,106 @@ components:
           schema: { $ref: "#/components/schemas/Problem" }
 
   schemas:
+    NotificationPreferences:
+      type: object
+      required:
+        - enabled
+        - sound
+        - previews
+      properties:
+        enabled:
+          type: boolean
+        sound:
+          type: boolean
+        previews:
+          type: boolean
+    NotificationSettings:
+      type: object
+      required:
+        - preferences
+        - mutes
+        - web_push
+        - android_push
+        - ios_push
+        - vapid_public_key
+      properties:
+        preferences:
+          $ref: "#/components/schemas/NotificationPreferences"
+        mutes:
+          type: array
+          items:
+            type: object
+            required:
+              - chat_id
+              - until
+            properties:
+              chat_id:
+                $ref: "#/components/schemas/Id"
+              until:
+                type: string
+                format: date-time
+        web_push:
+          type: boolean
+        android_push:
+          type: boolean
+        ios_push:
+          type: boolean
+        vapid_public_key:
+          type: string
+    NotificationDeviceRequest:
+      type: object
+      required:
+        - platform
+        - destination
+      properties:
+        platform:
+          type: string
+          enum:
+            - web
+            - android
+            - ios
+        destination:
+          type: string
+          minLength: 1
+          maxLength: 4096
+        p256dh:
+          type: string
+          maxLength: 128
+        auth:
+          type: string
+          maxLength: 64
+    NotificationDeviceRegistered:
+      type: object
+      required:
+        - id
+      properties:
+        id:
+          type: string
+          format: uuid
+    NotificationMuteRequest:
+      type: object
+      required:
+        - duration
+      properties:
+        duration:
+          type: string
+          enum:
+            - off
+            - 1h
+            - 8h
+            - forever
+    NotificationActivity:
+      type: object
+      required:
+        - active
+        - client_id
+      properties:
+        active:
+          type: boolean
+        client_id:
+          type: string
+          format: uuid
+
     # ---------------------------------------------------------- basics
     Id:
       type: string
@@ -2133,7 +2551,9 @@ components:
           description: A code of the authenticator app, or an unused recovery code.
     Visibility:
       type: string
-      description: Who may see the item. `*_except` scopes use the exception lists.
+      description: |
+        Who may see the item. The exception lists apply to every value; `*_except` behave like `everyone` and `nobody`.
+        `contacts` are the users you share a group with, or a direct chat that you opened or read in.
       enum: [everyone, contacts, everyone_except, nobody_except, nobody]
     DirectMessagePolicy:
       type: string
@@ -2146,7 +2566,7 @@ components:
       enum: [everyone, nobody]
     PrivacyExceptions:
       type: object
-      description: User IDs per setting; `allow` applies to `nobody_except`, `deny` to `everyone_except`.
+      description: User IDs per setting. An exception wins over the setting whatever its value; `allow` always lets the user in, `deny` always keeps them out.
       additionalProperties:
         type: object
         required: [allow, deny]
@@ -2211,7 +2631,7 @@ components:
           description: The requesting user's own name for this user, if set.
         avatar_url:
           type: [string, "null"]
-          description: Path of the avatar, always same-origin (`/api/v2/users/{id}/avatar`).
+          description: Path of the avatar, always same-origin (`/api/v2/users/{id}/avatar?rev={revision}`).
         bio: { type: [string, "null"] }
         is_online: { type: boolean }
         last_seen:
@@ -2328,6 +2748,29 @@ components:
             - $ref: "#/components/schemas/Id"
             - type: "null"
         sender_name: { type: string }
+    ReplyPreview:
+      type: object
+      description: |
+        What a reply shows of the message it answers, so a client can draw the quote without loading that
+        message. Set on messages of history pages and `message` events when the recipient can see the answered
+        message; absent when it is gone or hidden for them, and on chat-list previews and search results.
+      required: [id, type, sender, content, attachment, is_deleted]
+      properties:
+        id: { $ref: "#/components/schemas/Id" }
+        type: { $ref: "#/components/schemas/MessageType" }
+        sender:
+          oneOf:
+            - $ref: "#/components/schemas/User"
+            - type: "null"
+        content:
+          type: [string, "null"]
+          maxLength: 100
+          description: The first 100 characters of the text or caption; `null` when deleted or empty.
+        attachment:
+          oneOf:
+            - $ref: "#/components/schemas/Attachment"
+            - type: "null"
+        is_deleted: { type: boolean }
     Message:
       type: object
       required:
@@ -2365,6 +2808,8 @@ components:
           oneOf:
             - $ref: "#/components/schemas/Id"
             - type: "null"
+        reply_preview:
+          $ref: "#/components/schemas/ReplyPreview"
         forwarded_from:
           oneOf:
             - $ref: "#/components/schemas/ForwardedFrom"
@@ -2458,7 +2903,10 @@ components:
       type: object
       required: [content]
       properties:
-        content: { type: string, minLength: 1, maxLength: 4096 }
+        content:
+          type: string
+          maxLength: 4096
+          description: New text, or the new caption of a file. Empty removes a file's caption; a text message rejects it.
     ForwardMessageRequest:
       type: object
       required: [chat_ids]
@@ -2469,6 +2917,35 @@ components:
           maxItems: 20
           uniqueItems: true
           items: { $ref: "#/components/schemas/Id" }
+    ForwardMessagesRequest:
+      type: object
+      required: [message_ids, chat_ids]
+      properties:
+        message_ids:
+          type: array
+          minItems: 1
+          maxItems: 20
+          uniqueItems: true
+          items: { $ref: "#/components/schemas/Id" }
+        chat_ids:
+          type: array
+          minItems: 1
+          maxItems: 20
+          uniqueItems: true
+          items: { $ref: "#/components/schemas/Id" }
+    DeleteMessagesRequest:
+      type: object
+      required: [message_ids, scope]
+      properties:
+        message_ids:
+          type: array
+          minItems: 1
+          maxItems: 100
+          uniqueItems: true
+          items: { $ref: "#/components/schemas/Id" }
+        scope:
+          type: string
+          enum: [me, everyone]
     MarkReadRequest:
       type: object
       required: [message_id]