@myronsi/messenger-api 2.1.0-alpha.11 → 2.1.0-alpha.12

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.1.0-alpha.12
+
+- `GET /link-preview?url=` returns the Open Graph preview of a public web page (`title`, `description`,
+  `site_name`, `image`), cached for a day. `image.url` points to `GET /link-preview/image`, which streams the
+  picture through the server (PNG, JPEG, GIF or WebP up to 5 MB) with a signature, so clients never load
+  third-party images directly. Only public `http`/`https` addresses on ports 80 and 443 are fetched.
+- Messages have an optional `system_event` (`kind`, `actor_id`, `actor_name`, `target_id`, `target_name`) on
+  `system` messages, whose `content` is then `null`. Groups write them when a group is created and when members
+  are added, join, are removed or leave. System messages do not count as unread.
+- `GET /groups/{chat_id}/role-log` lists who changed whose role and when, newest first (members only).
+- `GroupRole` and `UpdateRoleRequest` have `moderator` again: moderators may delete other members' messages.
+- In a direct chat either side may delete any message for everyone (`DELETE /messages/{message_id}?scope=everyone`
+  and `POST /chats/{chat_id}/messages/delete`).
+- The last message of a chat (`GET /chats`, `GET /chats/{chat_id}`) skips messages deleted for everyone and is the
+  newest message that still has content.
+
 ## 2.1.0-alpha.11
 
 - Attachments have `display_url`: a JPEG of at most 1600 px (`GET /attachments/{attachment_id}/content?variant=display`)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.11. Do not edit. */
-export declare const API_VERSION: "2.1.0-alpha.11";
+/* Generated from api/openapi.yaml 2.1.0-alpha.12. Do not edit. */
+export declare const API_VERSION: "2.1.0-alpha.12";
 export type { paths, components, operations } from "./schema.js";
 export * from "./ws-events.js";

package/dist/index.js

@@ -1 +1 @@
-export const API_VERSION = "2.1.0-alpha.11";
+export const API_VERSION = "2.1.0-alpha.12";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.1.0-alpha.11
+  version: 2.1.0-alpha.12
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -1356,7 +1356,8 @@ paths:
       summary: Delete a message
       description: |
         `scope=me` hides it for the current user only (any message). `scope=everyone` removes
-        it for all participants (own messages, and any message for group admins).
+        it for all participants: own messages, any message of a direct chat (either side), and any message
+        for group owners, admins and moderators.
       parameters:
         - name: scope
           in: query
@@ -1829,6 +1830,89 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
         "409": { $ref: "#/components/responses/Conflict" }
+  /groups/{chat_id}/role-log:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+      - $ref: "#/components/parameters/ChatId"
+    get:
+      tags: [groups]
+      operationId: getGroupRoleLog
+      summary: Role changes of the group's members
+      description: Who made whom an admin or a member, or transferred ownership, and when. Members only.
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "200":
+          description: Role changes
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/GroupRoleLog" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "404": { $ref: "#/components/responses/NotFound" }
+  /link-preview:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    get:
+      tags: [messages]
+      operationId: getLinkPreview
+      summary: Preview of a web page for a link in a message
+      description: |
+        Reads the page's Open Graph data (`og:title`, `og:description`, `og:site_name`, `og:image`; falling back to
+        `<title>`, `description` and `twitter:image`). Only public `http`/`https` addresses on ports 80 and 443
+        are fetched. Answers are cached for a day (a page without a preview for an hour). `image.url` points to
+        `GET /link-preview/image`, so clients never load third-party images directly. `404` when the page has
+        no preview or cannot be fetched.
+      parameters:
+        - name: url
+          in: query
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 2048 }
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "200":
+          description: The preview
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LinkPreview" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+  /link-preview/image:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    get:
+      tags: [messages]
+      operationId: getLinkPreviewImage
+      summary: The image of a link preview, through the server
+      description: |
+        Use the `image.url` of a link preview as it is; `sig` proves the server made it. PNG, JPEG, GIF and WebP
+        up to 5 MB, sent with `X-Content-Type-Options: nosniff`.
+      parameters:
+        - name: url
+          in: query
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 2048 }
+        - name: sig
+          in: query
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 64 }
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "200":
+          description: Image content
+          content:
+            image/*:
+              schema: { type: string, format: binary }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
 
   /me/notifications:
     get:
@@ -2833,7 +2917,51 @@ components:
             - $ref: "#/components/schemas/Timestamp"
             - type: "null"
         is_deleted: { type: boolean }
+        system_event:
+          $ref: "#/components/schemas/SystemEvent"
         client_temp_id: { $ref: "#/components/schemas/ClientTempId" }
+    LinkPreview:
+      type: object
+      required: [url, title, description, site_name, image]
+      properties:
+        url:
+          type: string
+          description: The page after redirects
+        title: { type: [string, "null"], maxLength: 300 }
+        description: { type: [string, "null"], maxLength: 500 }
+        site_name: { type: [string, "null"], maxLength: 100 }
+        image:
+          oneOf:
+            - $ref: "#/components/schemas/LinkPreviewImage"
+            - type: "null"
+    LinkPreviewImage:
+      type: object
+      required: [url, width, height]
+      properties:
+        url:
+          type: string
+          description: "`GET /link-preview/image` with the signed address of the page's image"
+        width: { type: [integer, "null"], minimum: 1 }
+        height: { type: [integer, "null"], minimum: 1 }
+    SystemEventKind:
+      type: string
+      enum: [group_created, member_added, member_joined, member_removed, member_left]
+    SystemEvent:
+      type: object
+      description: |
+        What a `system` message records; set on system messages only, whose `content` is then `null`. The names
+        are the display names at the time of the event. `target` fields are set for `member_added` and
+        `member_removed`.
+      required: [kind, actor_id, actor_name]
+      properties:
+        kind: { $ref: "#/components/schemas/SystemEventKind" }
+        actor_id:
+          oneOf:
+            - $ref: "#/components/schemas/Id"
+            - type: "null"
+        actor_name: { type: string }
+        target_id: { $ref: "#/components/schemas/Id" }
+        target_name: { type: string }
     MessagePage:
       type: object
       required: [items, next_cursor, prev_cursor]
@@ -2967,7 +3095,30 @@ components:
       enum: [direct, group]
     GroupRole:
       type: string
-      enum: [owner, admin, member]
+      description: A moderator may delete other members' messages; owners and admins also manage the group.
+      enum: [owner, admin, moderator, member]
+    GroupRoleEvent:
+      type: object
+      description: A member got a new role; `owner` means the actor transferred ownership to them.
+      required: [id, actor, target, role, created_at]
+      properties:
+        id: { $ref: "#/components/schemas/Id" }
+        actor:
+          description: "`null` when the account is gone."
+          oneOf:
+            - $ref: "#/components/schemas/User"
+            - type: "null"
+        target: { $ref: "#/components/schemas/User" }
+        role: { $ref: "#/components/schemas/GroupRole" }
+        created_at: { $ref: "#/components/schemas/Timestamp" }
+    GroupRoleLog:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          description: Newest first, at most 100
+          items: { $ref: "#/components/schemas/GroupRoleEvent" }
     Chat:
       type: object
       required:
@@ -3069,7 +3220,7 @@ components:
       properties:
         role:
           type: string
-          enum: [admin, member]
+          enum: [admin, moderator, member]
     TransferOwnerRequest:
       type: object
       required: [user_id]

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.11. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.12. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -1070,7 +1070,8 @@ export interface paths {
         /**
          * Delete a message
          * @description `scope=me` hides it for the current user only (any message). `scope=everyone` removes
-         *     it for all participants (own messages, and any message for group admins).
+         *     it for all participants: own messages, any message of a direct chat (either side), and any message
+         *     for group owners, admins and moderators.
          */
         delete: operations["deleteMessage"];
         options?: never;
@@ -1447,6 +1448,88 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/groups/{chat_id}/role-log": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path: {
+                chat_id: components["parameters"]["ChatId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Role changes of the group's members
+         * @description Who made whom an admin or a member, or transferred ownership, and when. Members only.
+         */
+        get: operations["getGroupRoleLog"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/link-preview": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Preview of a web page for a link in a message
+         * @description Reads the page's Open Graph data (`og:title`, `og:description`, `og:site_name`, `og:image`; falling back to
+         *     `<title>`, `description` and `twitter:image`). Only public `http`/`https` addresses on ports 80 and 443
+         *     are fetched. Answers are cached for a day (a page without a preview for an hour). `image.url` points to
+         *     `GET /link-preview/image`, so clients never load third-party images directly. `404` when the page has
+         *     no preview or cannot be fetched.
+         */
+        get: operations["getLinkPreview"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/link-preview/image": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The image of a link preview, through the server
+         * @description Use the `image.url` of a link preview as it is; `sig` proves the server made it. PNG, JPEG, GIF and WebP
+         *     up to 5 MB, sent with `X-Content-Type-Options: nosniff`.
+         */
+        get: operations["getLinkPreviewImage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/me/notifications": {
         parameters: {
             query?: never;
@@ -1964,8 +2047,37 @@ export interface components {
             created_at: components["schemas"]["Timestamp"];
             edited_at: components["schemas"]["Timestamp"] | null;
             is_deleted: boolean;
+            system_event?: components["schemas"]["SystemEvent"];
             client_temp_id?: components["schemas"]["ClientTempId"];
         };
+        LinkPreview: {
+            /** @description The page after redirects */
+            url: string;
+            title: string | null;
+            description: string | null;
+            site_name: string | null;
+            image: components["schemas"]["LinkPreviewImage"] | null;
+        };
+        LinkPreviewImage: {
+            /** @description `GET /link-preview/image` with the signed address of the page's image */
+            url: string;
+            width: number | null;
+            height: number | null;
+        };
+        /** @enum {string} */
+        SystemEventKind: "group_created" | "member_added" | "member_joined" | "member_removed" | "member_left";
+        /**
+         * @description What a `system` message records; set on system messages only, whose `content` is then `null`. The names
+         *     are the display names at the time of the event. `target` fields are set for `member_added` and
+         *     `member_removed`.
+         */
+        SystemEvent: {
+            kind: components["schemas"]["SystemEventKind"];
+            actor_id: components["schemas"]["Id"] | null;
+            actor_name: string;
+            target_id?: components["schemas"]["Id"];
+            target_name?: string;
+        };
         MessagePage: {
             /** @description Oldest to newest */
             items: components["schemas"]["Message"][];
@@ -2022,8 +2134,24 @@ export interface components {
         };
         /** @enum {string} */
         ChatType: "direct" | "group";
-        /** @enum {string} */
-        GroupRole: "owner" | "admin" | "member";
+        /**
+         * @description A moderator may delete other members' messages; owners and admins also manage the group.
+         * @enum {string}
+         */
+        GroupRole: "owner" | "admin" | "moderator" | "member";
+        /** @description A member got a new role; `owner` means the actor transferred ownership to them. */
+        GroupRoleEvent: {
+            id: components["schemas"]["Id"];
+            /** @description `null` when the account is gone. */
+            actor: components["schemas"]["User"] | null;
+            target: components["schemas"]["User"];
+            role: components["schemas"]["GroupRole"];
+            created_at: components["schemas"]["Timestamp"];
+        };
+        GroupRoleLog: {
+            /** @description Newest first, at most 100 */
+            items: components["schemas"]["GroupRoleEvent"][];
+        };
         Chat: {
             id: components["schemas"]["Id"];
             type: components["schemas"]["ChatType"];
@@ -2076,7 +2204,7 @@ export interface components {
         };
         UpdateRoleRequest: {
             /** @enum {string} */
-            role: "admin" | "member";
+            role: "admin" | "moderator" | "member";
         };
         TransferOwnerRequest: {
             user_id: components["schemas"]["Id"];
@@ -4739,6 +4867,104 @@ export interface operations {
             426: components["responses"]["ClientOutdated"];
         };
     };
+    getGroupRoleLog: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path: {
+                chat_id: components["parameters"]["ChatId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Role changes */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GroupRoleLog"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            426: components["responses"]["ClientOutdated"];
+        };
+    };
+    getLinkPreview: {
+        parameters: {
+            query: {
+                url: string;
+            };
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The preview */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LinkPreview"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    getLinkPreviewImage: {
+        parameters: {
+            query: {
+                url: string;
+                sig: string;
+            };
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Image content */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "image/*": string;
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getNotificationSettings: {
         parameters: {
             query?: never;

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.11. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.12. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -57,7 +57,11 @@ export type Username = string;
 export type ChatType = "direct" | "group";
 export type MessageType = "text" | "file" | "voice" | "system";
 export type AttachmentKind = "image" | "audio" | "voice" | "video" | "file";
-export type GroupRole = "owner" | "admin" | "member";
+export type SystemEventKind = "group_created" | "member_added" | "member_joined" | "member_removed" | "member_left";
+/**
+ * A moderator may delete other members' messages; owners and admins also manage the group.
+ */
+export type GroupRole = "owner" | "admin" | "moderator" | "member";
 /**
  * Stable machine-readable error code. New codes can appear in MINOR versions; unknown
  * codes must be treated like `internal_error`.
@@ -314,6 +318,7 @@ export interface Message {
   created_at: Timestamp;
   edited_at: Timestamp | null;
   is_deleted: boolean;
+  system_event?: SystemEvent;
   client_temp_id?: ClientTempId;
 }
 export interface Attachment {
@@ -372,6 +377,19 @@ export interface ReadReceipt {
   user_id: Id;
   read_at: Timestamp;
 }
+/**
+ * What a `system` message records; set on system messages only, whose `content` is then `null`. The names
+ * are the display names at the time of the event. `target` fields are set for `member_added` and
+ * `member_removed`.
+ *
+ */
+export interface SystemEvent {
+  kind: SystemEventKind;
+  actor_id: Id | null;
+  actor_name: string;
+  target_id?: Id;
+  target_name?: string;
+}
 /**
  * A chat was deleted, or you were removed from it.
  */

package/dist/ws-events.schema.json

@@ -1442,11 +1442,132 @@
         "is_deleted": {
           "type": "boolean"
         },
+        "system_event": {
+          "$ref": "#/$defs/SystemEvent"
+        },
         "client_temp_id": {
           "$ref": "#/$defs/ClientTempId"
         }
       }
     },
+    "LinkPreview": {
+      "type": "object",
+      "required": [
+        "url",
+        "title",
+        "description",
+        "site_name",
+        "image"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "The page after redirects"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 300
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 500
+        },
+        "site_name": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 100
+        },
+        "image": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/LinkPreviewImage"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "LinkPreviewImage": {
+      "type": "object",
+      "required": [
+        "url",
+        "width",
+        "height"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "`GET /link-preview/image` with the signed address of the page's image"
+        },
+        "width": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        },
+        "height": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        }
+      }
+    },
+    "SystemEventKind": {
+      "type": "string",
+      "enum": [
+        "group_created",
+        "member_added",
+        "member_joined",
+        "member_removed",
+        "member_left"
+      ]
+    },
+    "SystemEvent": {
+      "type": "object",
+      "description": "What a `system` message records; set on system messages only, whose `content` is then `null`. The names\nare the display names at the time of the event. `target` fields are set for `member_added` and\n`member_removed`.\n",
+      "required": [
+        "kind",
+        "actor_id",
+        "actor_name"
+      ],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/SystemEventKind"
+        },
+        "actor_id": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Id"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "actor_name": {
+          "type": "string"
+        },
+        "target_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "target_name": {
+          "type": "string"
+        }
+      }
+    },
     "MessagePage": {
       "type": "object",
       "required": [
@@ -1708,12 +1829,65 @@
     },
     "GroupRole": {
       "type": "string",
+      "description": "A moderator may delete other members' messages; owners and admins also manage the group.",
       "enum": [
         "owner",
         "admin",
+        "moderator",
         "member"
       ]
     },
+    "GroupRoleEvent": {
+      "type": "object",
+      "description": "A member got a new role; `owner` means the actor transferred ownership to them.",
+      "required": [
+        "id",
+        "actor",
+        "target",
+        "role",
+        "created_at"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/Id"
+        },
+        "actor": {
+          "description": "`null` when the account is gone.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/User"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "target": {
+          "$ref": "#/$defs/User"
+        },
+        "role": {
+          "$ref": "#/$defs/GroupRole"
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      }
+    },
+    "GroupRoleLog": {
+      "type": "object",
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "description": "Newest first, at most 100",
+          "items": {
+            "$ref": "#/$defs/GroupRoleEvent"
+          }
+        }
+      }
+    },
     "Chat": {
       "type": "object",
       "required": [
@@ -1962,6 +2136,7 @@
           "type": "string",
           "enum": [
             "admin",
+            "moderator",
             "member"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myronsi/messenger-api",
-  "version": "2.1.0-alpha.11",
+  "version": "2.1.0-alpha.12",
   "description": "API contract of the Messenger backend: OpenAPI document, WebSocket event schemas and generated TypeScript types",
   "license": "MIT",
   "repository": {