@myronsi/messenger-api 2.0.0-alpha.3.next.42 → 2.0.0-alpha.4.next.44

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 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.4. Do not edit. */
+export declare const API_VERSION: "2.0.0-alpha.4";
 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.4";

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.4
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -727,7 +727,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 +850,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" }
@@ -1558,7 +1577,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 +1660,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 +1848,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 +2045,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 +2200,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 +2212,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.4. 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;
@@ -1232,6 +1237,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 +1352,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 +1471,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 +1547,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 +1740,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;
@@ -2715,7 +2726,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 +2899,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"];

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.4. 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.4.next.44",
   "description": "API contract of the Messenger backend: OpenAPI document, WebSocket event schemas and generated TypeScript types",
   "license": "MIT",
   "repository": {