@myronsi/messenger-api 2.0.0-alpha.2.next.34 → 2.0.0-alpha.4.next.44

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.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):
+
+- Optional `api_version` query parameter on `/api/v2/ws`: browsers cannot send `X-Client-Api-Version` on a WebSocket, so a client passes its contract version here and an outdated one gets `hello` and then close code `4426`.
+- Close codes: `4401` also when the session of the connection ends (logout, revoked session, password change); `1012` "reconnect" also after the server lost its pub/sub connection (events may be missing, so the client catches up); `1013` when the client cannot keep up with its events.
+- A user removed from a chat gets `chat_deleted` and no further events of that chat.
+
 ## 2.0.0-alpha.2
 
 Authentication details found while implementing the Go backend:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.2. Do not edit. */
-export declare const API_VERSION: "2.0.0-alpha.2";
+/* 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.2";
+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.2
+  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.2. 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-docs.json

@@ -1,5 +1,5 @@
 {
-  "markdown": "# WebSocket protocol (API contract v2)\n\nThe JSON Schemas in `websocket/client/` (client → server) and `websocket/server/` (server → client) are the source of truth. Every event has an example in `websocket/examples/`, validated against its schema by `npm run check`. TypeScript types are generated into `dist/ws-events.d.ts` (`ClientEvent`, `ServerEvent`).\n\n## Connecting\n\n1. `POST /api/v2/ws/ticket` (authenticated) returns `{ \"ticket\": \"…\", \"expires_in\": 30 }`. The ticket is single-use and short-lived, so no access token ends up in a URL or a log.\n2. Open **one connection per user**: `wss://<host>/api/v2/ws?ticket=<ticket>`. The connection carries the events of all chats of the user.\n3. The first server event is `hello` with `api_version` and `min_client_api_version`. A client that reconnects after a deploy compares them with the contract version it was built for and shows an upgrade notice instead of failing at random.\n4. When the ticket is invalid or expired the server closes the connection with code `4401`. An outdated client is closed with `4426` after `hello`.\n\n## Envelope\n\nServer → client:\n\n```json\n{ \"type\": \"message\", \"event_id\": \"7217400317439950849\", \"chat_id\": \"42\", \"data\": { \"message\": { \"…\": \"…\" } } }\n```\n\nClient → server:\n\n```json\n{ \"type\": \"message\", \"client_temp_id\": \"c-1\", \"chat_id\": \"42\", \"data\": { \"type\": \"text\", \"content\": \"Hello!\" } }\n```\n\n- All IDs are strings (Snowflake IDs do not fit into a JavaScript number).\n- `event_id` is unique and increases per server; it is only for deduplication and logs.\n- `chat_id` is always `null` in `hello`, `presence` and `approval_request_created`, which do not belong to a chat. `ack` and `error` repeat the `chat_id` of the client event they answer, and it is `null` for connection-level errors.\n- Unknown event `type`s must be ignored by clients, so new event types are not a breaking change.\n\n## Acknowledgements\n\nEvery client event except `typing` (which is not acknowledged and carries no `client_temp_id`) has a `client_temp_id` (1–64 characters, unique per client). The server answers with exactly one of:\n\n- `ack` — `client_temp_id`, and for `message` the stored `message_id` and `created_at`. Sending the same `client_temp_id` again returns the same `ack` (idempotent), which makes retries after a reconnect safe.\n- `error` — `client_temp_id` and `data.code`/`data.message`. `code` is one of the stable codes of `ErrorCode` in `openapi.yaml` (the same codes as the REST `application/problem+json` errors).\n\nThe sender also receives the broadcast `message` event with the stored message (its `client_temp_id` is included, so the client can replace its pending copy).\n\n## Client → server events\n\n| Type | Purpose |\n| --- | --- |\n| `message` | Send a message (`type` `text`, `file` or `voice`; files are referenced by `attachment_id`, never by URL) |\n| `resend` | Deliver a stored but undelivered message again |\n| `edit` | Edit your own text message |\n| `delete` | Delete a message for yourself (`scope: me`) or everyone |\n| `read` | Mark messages as read up to `message_id` |\n| `reaction_add`, `reaction_remove` | Add or remove a reaction |\n| `typing` | Typing indicator (not acknowledged) |\n\n## Server → client events\n\n| Type | Meaning |\n| --- | --- |\n| `hello` | First event: `api_version`, `min_client_api_version`, `user_id` |\n| `ack`, `error` | Result of a client event, references `client_temp_id` |\n| `message`, `edit`, `delete` | Message created, edited or deleted |\n| `reaction_add`, `reaction_remove` | Reactions changed |\n| `read` | A user read up to `message_id` |\n| `typing` | A user is typing |\n| `chat_created`, `chat_deleted`, `chat_list_update` | Chat list changes |\n| `group_created`, `group_updated` | Group changes (members, roles, name, avatar) |\n| `approval_request_created` | New request in the inbox |\n| `presence` | A user came online or went offline |\n\n## Compatibility\n\nAdding an event type or an optional field is a MINOR change; removing or renaming an event or field, or making a field required, is MAJOR (see `docs/api-compatibility.md`). Clients must ignore unknown events and unknown fields.\n",
+  "markdown": "# WebSocket protocol (API contract v2)\r\n\r\nThe JSON Schemas in `websocket/client/` (client → server) and `websocket/server/` (server → client) are the source of truth. Every event has an example in `websocket/examples/`, validated against its schema by `npm run check`. TypeScript types are generated into `dist/ws-events.d.ts` (`ClientEvent`, `ServerEvent`).\r\n\r\n## Connecting\r\n\r\n1. `POST /api/v2/ws/ticket` (authenticated) returns `{ \"ticket\": \"…\", \"expires_in\": 30 }`. The ticket is single-use and short-lived, so no access token ends up in a URL or a log.\r\n2. Open **one connection per browser tab**: `wss://<host>/api/v2/ws?ticket=<ticket>&api_version=<contract version>`. The connection carries the events of all chats of the user. `api_version` is optional and takes the place of the `X-Client-Api-Version` header, which browsers cannot send on a WebSocket.\r\n3. The first server event is `hello` with `api_version` and `min_client_api_version`. A client that reconnects after a deploy compares them with the contract version it was built for and shows an upgrade notice instead of failing at random.\r\n4. When the ticket is invalid or expired the server closes the connection with code `4401`. A client whose `api_version` is no longer served is closed with `4426` after `hello`.\r\n\r\n## Close codes\r\n\r\n| Code | Meaning | Client |\r\n| --- | --- | --- |\r\n| `1012` | `reconnect`: the server is restarting, or it lost its pub/sub connection and events may be missing | reconnect with backoff, then load what was missed (`after` cursor) |\r\n| `1013` | the client did not keep up with its events | reconnect, then catch up |\r\n| `4401` | invalid ticket, or the session ended (logout, revoked, password changed) | get a new ticket; if that fails, sign in again |\r\n| `4426` | the client's contract version is no longer served | show the upgrade notice |\r\n\r\n## Envelope\r\n\r\nServer → client:\r\n\r\n```json\r\n{ \"type\": \"message\", \"event_id\": \"7217400317439950849\", \"chat_id\": \"42\", \"data\": { \"message\": { \"…\": \"…\" } } }\r\n```\r\n\r\nClient → server:\r\n\r\n```json\r\n{ \"type\": \"message\", \"client_temp_id\": \"c-1\", \"chat_id\": \"42\", \"data\": { \"type\": \"text\", \"content\": \"Hello!\" } }\r\n```\r\n\r\n- All IDs are strings (Snowflake IDs do not fit into a JavaScript number).\r\n- `event_id` is unique and increases per server; it is only for deduplication and logs.\r\n- `chat_id` is always `null` in `hello`, `presence` and `approval_request_created`, which do not belong to a chat. `ack` and `error` repeat the `chat_id` of the client event they answer, and it is `null` for connection-level errors.\r\n- Unknown event `type`s must be ignored by clients, so new event types are not a breaking change.\r\n- A user who is removed from a chat (or whose chat is deleted) receives `chat_deleted` and no further events of that chat.\r\n\r\n## Acknowledgements\r\n\r\nEvery client event except `typing` (which is not acknowledged and carries no `client_temp_id`) has a `client_temp_id` (1–64 characters, unique per client). The server answers with exactly one of:\r\n\r\n- `ack` — `client_temp_id`, and for `message` the stored `message_id` and `created_at`. Sending the same `client_temp_id` again returns the same `ack` (idempotent), which makes retries after a reconnect safe.\r\n- `error` — `client_temp_id` and `data.code`/`data.message`. `code` is one of the stable codes of `ErrorCode` in `openapi.yaml` (the same codes as the REST `application/problem+json` errors).\r\n\r\nThe sender also receives the broadcast `message` event with the stored message (its `client_temp_id` is included, so the client can replace its pending copy).\r\n\r\n## Client → server events\r\n\r\n| Type | Purpose |\r\n| --- | --- |\r\n| `message` | Send a message (`type` `text`, `file` or `voice`; files are referenced by `attachment_id`, never by URL) |\r\n| `resend` | Deliver a stored but undelivered message again |\r\n| `edit` | Edit your own text message |\r\n| `delete` | Delete a message for yourself (`scope: me`) or everyone |\r\n| `read` | Mark messages as read up to `message_id` |\r\n| `reaction_add`, `reaction_remove` | Add or remove a reaction |\r\n| `typing` | Typing indicator (not acknowledged) |\r\n\r\n## Server → client events\r\n\r\n| Type | Meaning |\r\n| --- | --- |\r\n| `hello` | First event: `api_version`, `min_client_api_version`, `user_id` |\r\n| `ack`, `error` | Result of a client event, references `client_temp_id` |\r\n| `message`, `edit`, `delete` | Message created, edited or deleted |\r\n| `reaction_add`, `reaction_remove` | Reactions changed |\r\n| `read` | A user read up to `message_id` |\r\n| `typing` | A user is typing |\r\n| `chat_created`, `chat_deleted`, `chat_list_update` | Chat list changes |\r\n| `group_created`, `group_updated` | Group changes (members, roles, name, avatar) |\r\n| `approval_request_created` | New request in the inbox |\r\n| `presence` | A user came online or went offline |\r\n\r\n## Compatibility\r\n\r\nAdding an event type or an optional field is a MINOR change; removing or renaming an event or field, or making a field required, is MAJOR (see `docs/api-compatibility.md`). Clients must ignore unknown events and unknown fields.\r\n",
   "examples": {
     "client/delete.json": {
       "type": "delete",

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.2. 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.2.next.34",
+  "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": {