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

package/dist/ws-docs.json

@@ -1,5 +1,5 @@
 {
-  "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",
+  "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, or sent more than 64 events that are not handled yet | 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| `4429` | the user opened more than 10 connections on this server; the oldest one is closed | do not reconnect this tab automatically |\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.1.0-alpha.1. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.10. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -97,7 +97,7 @@ export interface ClientDeleteEvent {
   };
 }
 /**
- * Edit your own text message.
+ * Edit your own text message or the caption of your file. An empty content removes a file's caption.
  */
 export interface ClientEditEvent {
   type: "edit";
@@ -253,7 +253,7 @@ export interface User {
    */
   contact_name?: string | null;
   /**
-   * Path of the avatar, always same-origin (`/api/v2/users/{id}/avatar`).
+   * Path of the avatar, always same-origin (`/api/v2/users/{id}/avatar?rev={revision}`).
    */
   avatar_url: string | null;
   bio: string | null;
@@ -307,6 +307,7 @@ export interface Message {
   content: string | null;
   attachment: Attachment | null;
   reply_to: Id | null;
+  reply_preview?: ReplyPreview;
   forwarded_from: ForwardedFrom | null;
   reactions: Reaction[];
   read_by: ReadReceipt[];
@@ -337,6 +338,23 @@ export interface Attachment {
   duration_ms?: number | null;
   waveform?: number[] | null;
 }
+/**
+ * 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.
+ *
+ */
+export interface ReplyPreview {
+  id: Id;
+  type: MessageType;
+  sender: User | null;
+  /**
+   * The first 100 characters of the text or caption; `null` when deleted or empty.
+   */
+  content: string | null;
+  attachment: Attachment | null;
+  is_deleted: boolean;
+}
 export interface ForwardedFrom {
   message_id: Id;
   sender_id: Id | null;

package/dist/ws-events.schema.json

@@ -1,6 +1,147 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$defs": {
+    "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": "#/$defs/NotificationPreferences"
+        },
+        "mutes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "chat_id",
+              "until"
+            ],
+            "properties": {
+              "chat_id": {
+                "$ref": "#/$defs/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"
+        }
+      }
+    },
     "Id": {
       "type": "string",
       "pattern": "^[0-9]{1,19}$",
@@ -662,7 +803,7 @@
     },
     "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`.\n`contacts` are the users you share a group with, or a direct chat that you opened or read in.\n",
       "enum": [
         "everyone",
         "contacts",
@@ -699,7 +840,7 @@
     },
     "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": [
@@ -838,7 +979,7 @@
             "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": [
@@ -1135,6 +1276,57 @@
         }
       }
     },
+    "ReplyPreview": {
+      "type": "object",
+      "description": "What a reply shows of the message it answers, so a client can draw the quote without loading that\nmessage. Set on messages of history pages and `message` events when the recipient can see the answered\nmessage; absent when it is gone or hidden for them, and on chat-list previews and search results.\n",
+      "required": [
+        "id",
+        "type",
+        "sender",
+        "content",
+        "attachment",
+        "is_deleted"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/Id"
+        },
+        "type": {
+          "$ref": "#/$defs/MessageType"
+        },
+        "sender": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/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": "#/$defs/Attachment"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "is_deleted": {
+          "type": "boolean"
+        }
+      }
+    },
     "Message": {
       "type": "object",
       "required": [
@@ -1201,6 +1393,9 @@
             }
           ]
         },
+        "reply_preview": {
+          "$ref": "#/$defs/ReplyPreview"
+        },
         "forwarded_from": {
           "oneOf": [
             {
@@ -1410,8 +1605,8 @@
       "properties": {
         "content": {
           "type": "string",
-          "minLength": 1,
-          "maxLength": 4096
+          "maxLength": 4096,
+          "description": "New text, or the new caption of a file. Empty removes a file's caption; a text message rejects it."
         }
       }
     },
@@ -1432,6 +1627,58 @@
         }
       }
     },
+    "ForwardMessagesRequest": {
+      "type": "object",
+      "required": [
+        "message_ids",
+        "chat_ids"
+      ],
+      "properties": {
+        "message_ids": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/Id"
+          }
+        },
+        "chat_ids": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/Id"
+          }
+        }
+      }
+    },
+    "DeleteMessagesRequest": {
+      "type": "object",
+      "required": [
+        "message_ids",
+        "scope"
+      ],
+      "properties": {
+        "message_ids": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 100,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/Id"
+          }
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "me",
+            "everyone"
+          ]
+        }
+      }
+    },
     "MarkReadRequest": {
       "type": "object",
       "required": [
@@ -1824,7 +2071,7 @@
     },
     "ClientEditEvent": {
       "title": "ClientEditEvent",
-      "description": "Edit your own text message.",
+      "description": "Edit your own text message or the caption of your file. An empty content removes a file's caption.",
       "type": "object",
       "properties": {
         "type": {
@@ -1844,7 +2091,6 @@
             },
             "content": {
               "type": "string",
-              "minLength": 1,
               "maxLength": 4096
             }
           },

package/package.json

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