@myronsi/messenger-api 2.0.0-alpha.3.next.42 → 2.0.0-alpha.5.next.46

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.0.0-alpha.5
+
+Chats, found while implementing the chat list:
+
+- `DELETE /chats/{chat_id}` deletes a direct chat for both users (as v1 did), not "for yourself"; a group is `422`.
+- `POST /chats` can answer `422` (a chat with yourself, a too long `initial_message`).
+- `PUT /chats/{chat_id}/pin`: at most 10 pinned chats (`409`).
+- `GET /chats` documents its order, what `last_message` and its `read_by` hold, and that `unread_count` stops at 999.
+- `DELETE /me` can answer `429` (repeated wrong passwords).
+
+## 2.0.0-alpha.4
+
+Media, found while implementing uploads:
+
+- Attachment IDs are UUIDs (`AttachmentRef`, `format: uuid`) instead of decimal IDs: `Attachment.id`, the `attachment_id` path parameter, `attachment_id` of `SendMessageRequest`, `SetAvatarRequest` and the WebSocket `message` event.
+- `GET /attachments/{attachment_id}/content` takes `variant=thumbnail`, may answer `302` to a signed URL, and documents its `Content-Disposition` rules.
+- `GET /users/{user_id}/avatar` takes `version` (an `AvatarVersion.id`), which `AvatarVersion.url` points to.
+
 ## 2.0.0-alpha.3
 
 WebSocket details found while implementing the gateway (documentation of `websocket.md` only):

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1 @@
-export const API_VERSION = "2.0.0-alpha.3";
+export const API_VERSION = "2.0.0-alpha.5";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.0.0-alpha.3
+  version: 2.0.0-alpha.5
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -324,6 +324,7 @@ paths:
           description: Account deleted
         "401": { $ref: "#/components/responses/Unauthorized" }
         "403": { $ref: "#/components/responses/Forbidden" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
   /me/avatar:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -727,7 +728,14 @@ paths:
       tags: [users]
       operationId: getUserAvatar
       summary: Current avatar image
-      description: Respects the avatar visibility of the user; falls back to the default avatar.
+      description: |
+        Respects the avatar visibility of the user; falls back to the default avatar. With `version`, an
+        earlier avatar of the history (`AvatarVersion.url`).
+      parameters:
+        - name: version
+          in: query
+          description: "`id` of an `AvatarVersion` of this user."
+          schema: { $ref: "#/components/schemas/Id" }
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -843,7 +851,19 @@ paths:
       tags: [attachments]
       operationId: getAttachmentContent
       summary: Download an attachment
-      description: Only participants of the chat the attachment was sent to (and its uploader) can download it.
+      description: |
+        Only the uploader and members of a chat in which a message using the attachment is visible to them can
+        download it. The answer is the file, or a `302` redirect to a short-lived signed URL of the object
+        storage. Images, audio and video are sent `inline`; everything else as a download
+        (`Content-Disposition: attachment`, `application/octet-stream`), always with
+        `X-Content-Type-Options: nosniff`.
+      parameters:
+        - name: variant
+          in: query
+          description: "`thumbnail`: a JPEG of at most 320 px (images only; `thumbnail_url` of the attachment)."
+          schema:
+            type: string
+            enum: [thumbnail]
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -865,7 +885,12 @@ paths:
       tags: [chats]
       operationId: listChats
       summary: My chats with last message and unread count
-      description: One request replaces `GET /chats/list/{username}` and `GET /groups/list/{username}`; pinned chats come first.
+      description: |
+        One request replaces `GET /chats/list/{username}` and `GET /groups/list/{username}`.
+        Pinned chats come first (most recently pinned first), then the others by their last
+        message (newest first). `last_message` is the newest message the caller can see; in
+        direct chats its `read_by` holds the other user once they read it (with read receipts
+        on), in groups it is empty. `unread_count` stops at 999.
       parameters:
         - $ref: "#/components/parameters/Limit"
         - $ref: "#/components/parameters/After"
@@ -912,6 +937,7 @@ paths:
         "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}:
     parameters:
@@ -935,8 +961,11 @@ paths:
     delete:
       tags: [chats]
       operationId: deleteChat
-      summary: Delete a direct chat for yourself
-      description: For groups use `DELETE /groups/{chat_id}` (owner) or `POST /groups/{chat_id}/leave`.
+      summary: Delete a direct chat
+      description: |
+        Deletes the chat and its messages for both users (as v1 did); both get `chat_deleted`.
+        For groups use `DELETE /groups/{chat_id}` (owner) or `POST /groups/{chat_id}/leave`;
+        a group here is `422`.
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -944,6 +973,7 @@ paths:
           description: Deleted
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
   /chats/{chat_id}/pin:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -953,6 +983,7 @@ paths:
       tags: [chats]
       operationId: pinChat
       summary: Pin a chat
+      description: At most 10 chats can be pinned (`409` beyond that). Pinning a pinned chat changes nothing.
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
         "400": { $ref: "#/components/responses/BadRequest" }
@@ -1558,7 +1589,7 @@ components:
       name: attachment_id
       in: path
       required: true
-      schema: { $ref: "#/components/schemas/Id" }
+      schema: { $ref: "#/components/schemas/AttachmentRef" }
     SessionId:
       name: session_id
       in: path
@@ -1641,6 +1672,11 @@ components:
       pattern: "^[0-9]{1,19}$"
       description: Decimal ID as a string (Snowflake IDs exceed 2^53).
       examples: ["7217400317439950848"]
+    AttachmentRef:
+      type: string
+      format: uuid
+      description: ID of an uploaded attachment (a UUID, unlike the decimal IDs of messages, users and chats).
+      examples: ["5f0c8a64-2f2b-4c7e-9d0e-6b1f3a2c4d5e"]
     Cursor:
       type: [string, "null"]
       maxLength: 256
@@ -1824,7 +1860,7 @@ components:
       type: object
       required: [attachment_id]
       properties:
-        attachment_id: { $ref: "#/components/schemas/Id" }
+        attachment_id: { $ref: "#/components/schemas/AttachmentRef" }
     SecuritySettings:
       type: object
       required: [session_duration_days, two_factor_enabled]
@@ -2021,7 +2057,7 @@ components:
       type: object
       required: [id, kind, filename, content_type, size, url]
       properties:
-        id: { $ref: "#/components/schemas/Id" }
+        id: { $ref: "#/components/schemas/AttachmentRef" }
         kind: { $ref: "#/components/schemas/AttachmentKind" }
         filename: { type: string }
         content_type:
@@ -2176,7 +2212,7 @@ components:
         attachment_id:
           description: Required and not null for `file` and `voice`; never a URL.
           oneOf:
-            - $ref: "#/components/schemas/Id"
+            - $ref: "#/components/schemas/AttachmentRef"
             - type: "null"
         reply_to:
           oneOf:
@@ -2188,7 +2224,7 @@ components:
       then:
         required: [attachment_id]
         properties:
-          attachment_id: { $ref: "#/components/schemas/Id" }
+          attachment_id: { $ref: "#/components/schemas/AttachmentRef" }
       else:
         required: [content]
         properties:

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.3. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.5. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -613,7 +613,8 @@ export interface paths {
         };
         /**
          * Current avatar image
-         * @description Respects the avatar visibility of the user; falls back to the default avatar.
+         * @description Respects the avatar visibility of the user; falls back to the default avatar. With `version`, an
+         *     earlier avatar of the history (`AvatarVersion.url`).
          */
         get: operations["getUserAvatar"];
         put?: never;
@@ -716,7 +717,11 @@ export interface paths {
         };
         /**
          * Download an attachment
-         * @description Only participants of the chat the attachment was sent to (and its uploader) can download it.
+         * @description Only the uploader and members of a chat in which a message using the attachment is visible to them can
+         *     download it. The answer is the file, or a `302` redirect to a short-lived signed URL of the object
+         *     storage. Images, audio and video are sent `inline`; everything else as a download
+         *     (`Content-Disposition: attachment`, `application/octet-stream`), always with
+         *     `X-Content-Type-Options: nosniff`.
          */
         get: operations["getAttachmentContent"];
         put?: never;
@@ -741,7 +746,11 @@ export interface paths {
         };
         /**
          * My chats with last message and unread count
-         * @description One request replaces `GET /chats/list/{username}` and `GET /groups/list/{username}`; pinned chats come first.
+         * @description One request replaces `GET /chats/list/{username}` and `GET /groups/list/{username}`.
+         *     Pinned chats come first (most recently pinned first), then the others by their last
+         *     message (newest first). `last_message` is the newest message the caller can see; in
+         *     direct chats its `read_by` holds the other user once they read it (with read receipts
+         *     on), in groups it is empty. `unread_count` stops at 999.
          */
         get: operations["listChats"];
         put?: never;
@@ -777,8 +786,10 @@ export interface paths {
         put?: never;
         post?: never;
         /**
-         * Delete a direct chat for yourself
-         * @description For groups use `DELETE /groups/{chat_id}` (owner) or `POST /groups/{chat_id}/leave`.
+         * Delete a direct chat
+         * @description Deletes the chat and its messages for both users (as v1 did); both get `chat_deleted`.
+         *     For groups use `DELETE /groups/{chat_id}` (owner) or `POST /groups/{chat_id}/leave`;
+         *     a group here is `422`.
          */
         delete: operations["deleteChat"];
         options?: never;
@@ -801,7 +812,10 @@ export interface paths {
             cookie?: never;
         };
         get?: never;
-        /** Pin a chat */
+        /**
+         * Pin a chat
+         * @description At most 10 chats can be pinned (`409` beyond that). Pinning a pinned chat changes nothing.
+         */
         put: operations["pinChat"];
         post?: never;
         /** Unpin a chat */
@@ -1232,6 +1246,12 @@ export interface components {
          * @example 7217400317439950848
          */
         Id: string;
+        /**
+         * Format: uuid
+         * @description ID of an uploaded attachment (a UUID, unlike the decimal IDs of messages, users and chats).
+         * @example 5f0c8a64-2f2b-4c7e-9d0e-6b1f3a2c4d5e
+         */
+        AttachmentRef: string;
         /** @description Opaque cursor; `null` when there are no more results. */
         Cursor: string | null;
         /** Format: date-time */
@@ -1341,7 +1361,7 @@ export interface components {
             bio?: string | null;
         };
         SetAvatarRequest: {
-            attachment_id: components["schemas"]["Id"];
+            attachment_id: components["schemas"]["AttachmentRef"];
         };
         SecuritySettings: {
             session_duration_days: number;
@@ -1460,7 +1480,7 @@ export interface components {
             waveform?: number[];
         };
         Attachment: {
-            id: components["schemas"]["Id"];
+            id: components["schemas"]["AttachmentRef"];
             kind: components["schemas"]["AttachmentKind"];
             filename: string;
             /** @description Detected by the server */
@@ -1536,7 +1556,7 @@ export interface components {
             type: "text" | "file" | "voice";
             content?: string | null;
             /** @description Required and not null for `file` and `voice`; never a URL. */
-            attachment_id?: components["schemas"]["Id"] | null;
+            attachment_id?: components["schemas"]["AttachmentRef"] | null;
             reply_to?: components["schemas"]["Id"] | null;
         };
         EditMessageRequest: {
@@ -1729,7 +1749,7 @@ export interface components {
         MessageId: components["schemas"]["Id"];
         UserId: components["schemas"]["Id"];
         RequestId: components["schemas"]["Id"];
-        AttachmentId: components["schemas"]["Id"];
+        AttachmentId: components["schemas"]["AttachmentRef"];
         SessionId: string;
         /** @description Version of the client app, for logs and the per-client metric. */
         ClientVersion: string;
@@ -2079,6 +2099,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
         };
     };
     updateMe: {
@@ -2715,7 +2736,10 @@ export interface operations {
     };
     getUserAvatar: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description `id` of an `AvatarVersion` of this user. */
+                version?: components["schemas"]["Id"];
+            };
             header?: {
                 /** @description Version of the client app, for logs and the per-client metric. */
                 "X-Client-Version"?: components["parameters"]["ClientVersion"];
@@ -2885,7 +2909,10 @@ export interface operations {
     };
     getAttachmentContent: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description `thumbnail`: a JPEG of at most 320 px (images only; `thumbnail_url` of the attachment). */
+                variant?: "thumbnail";
+            };
             header?: {
                 /** @description Version of the client app, for logs and the per-client metric. */
                 "X-Client-Version"?: components["parameters"]["ClientVersion"];
@@ -2997,6 +3024,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
             429: components["responses"]["TooManyRequests"];
         };
@@ -3058,6 +3086,7 @@ export interface operations {
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
             404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
         };
     };

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.3. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.5. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -24,6 +24,10 @@ export type ClientTempId = string;
  * Decimal ID as a string (Snowflake IDs exceed 2^53).
  */
 export type Id = string;
+/**
+ * ID of an uploaded attachment (a UUID, unlike the decimal IDs of messages, users and chats).
+ */
+export type AttachmentRef = string;
 /**
  * Every event the server may send.
  */
@@ -126,7 +130,7 @@ export interface AttachmentMessageData {
    * Optional caption
    */
   content?: string | null;
-  attachment_id: Id;
+  attachment_id: AttachmentRef;
   reply_to?: Id | null;
 }
 /**
@@ -311,7 +315,7 @@ export interface Message {
   client_temp_id?: ClientTempId;
 }
 export interface Attachment {
-  id: Id;
+  id: AttachmentRef;
   kind: AttachmentKind;
   filename: string;
   /**

package/dist/ws-events.schema.json

@@ -9,6 +9,14 @@
         "7217400317439950848"
       ]
     },
+    "AttachmentRef": {
+      "type": "string",
+      "format": "uuid",
+      "description": "ID of an uploaded attachment (a UUID, unlike the decimal IDs of messages, users and chats).",
+      "examples": [
+        "5f0c8a64-2f2b-4c7e-9d0e-6b1f3a2c4d5e"
+      ]
+    },
     "Cursor": {
       "type": [
         "string",
@@ -407,7 +415,7 @@
       ],
       "properties": {
         "attachment_id": {
-          "$ref": "#/$defs/Id"
+          "$ref": "#/$defs/AttachmentRef"
         }
       }
     },
@@ -871,7 +879,7 @@
       ],
       "properties": {
         "id": {
-          "$ref": "#/$defs/Id"
+          "$ref": "#/$defs/AttachmentRef"
         },
         "kind": {
           "$ref": "#/$defs/AttachmentKind"
@@ -1221,7 +1229,7 @@
           "description": "Required and not null for `file` and `voice`; never a URL.",
           "oneOf": [
             {
-              "$ref": "#/$defs/Id"
+              "$ref": "#/$defs/AttachmentRef"
             },
             {
               "type": "null"
@@ -1255,7 +1263,7 @@
         ],
         "properties": {
           "attachment_id": {
-            "$ref": "#/$defs/Id"
+            "$ref": "#/$defs/AttachmentRef"
           }
         }
       },
@@ -1801,7 +1809,7 @@
                   "description": "Optional caption"
                 },
                 "attachment_id": {
-                  "$ref": "#/$defs/Id"
+                  "$ref": "#/$defs/AttachmentRef"
                 },
                 "reply_to": {
                   "oneOf": [

package/package.json

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