@myronsi/messenger-api 2.0.0-alpha.1.next.1

package/dist/ws-docs.json

@@ -0,0 +1,428 @@
+{
+  "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",
+  "examples": {
+    "client/delete.json": {
+      "type": "delete",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "scope": "everyone"
+      }
+    },
+    "client/edit.json": {
+      "type": "edit",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "content": "Hello, world!"
+      }
+    },
+    "client/message.json": {
+      "type": "message",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "type": "text",
+        "content": "Hello!"
+      }
+    },
+    "client/reaction_add.json": {
+      "type": "reaction_add",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "emoji": "👍"
+      }
+    },
+    "client/reaction_remove.json": {
+      "type": "reaction_remove",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "emoji": "👍"
+      }
+    },
+    "client/read.json": {
+      "type": "read",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001"
+      }
+    },
+    "client/resend.json": {
+      "type": "resend",
+      "client_temp_id": "c-1",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001"
+      }
+    },
+    "client/typing.json": {
+      "type": "typing",
+      "chat_id": "42",
+      "data": {
+        "is_typing": true
+      }
+    },
+    "server/ack.json": {
+      "type": "ack",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "created_at": "2026-10-04T12:00:00Z"
+      },
+      "client_temp_id": "c-1"
+    },
+    "server/approval_request_created.json": {
+      "type": "approval_request_created",
+      "event_id": "7217400317439950009",
+      "chat_id": null,
+      "data": {
+        "request": {
+          "id": "5",
+          "type": "direct_message",
+          "status": "pending",
+          "requester": {
+            "id": "1001",
+            "username": "alice",
+            "display_name": "Alice",
+            "avatar_url": "/api/v2/users/1001/avatar",
+            "bio": null,
+            "is_online": true,
+            "last_seen": null,
+            "is_deleted": false
+          },
+          "group_name": null,
+          "preview": "Hi, can we talk?",
+          "created_at": "2026-10-04T12:00:00Z"
+        }
+      }
+    },
+    "server/chat_created.json": {
+      "type": "chat_created",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "chat": {
+          "id": "42",
+          "type": "direct",
+          "name": "Alice",
+          "avatar_url": "/api/v2/users/1001/avatar",
+          "peer": {
+            "id": "1001",
+            "username": "alice",
+            "display_name": "Alice",
+            "avatar_url": "/api/v2/users/1001/avatar",
+            "bio": null,
+            "is_online": true,
+            "last_seen": null,
+            "is_deleted": false
+          },
+          "is_pinned": false,
+          "unread_count": 1,
+          "last_message": {
+            "id": "7217400317439950001",
+            "chat_id": "42",
+            "type": "text",
+            "sender": {
+              "id": "1001",
+              "username": "alice",
+              "display_name": "Alice",
+              "avatar_url": "/api/v2/users/1001/avatar",
+              "bio": null,
+              "is_online": true,
+              "last_seen": null,
+              "is_deleted": false
+            },
+            "content": "Hello!",
+            "attachment": null,
+            "reply_to": null,
+            "forwarded_from": null,
+            "reactions": [],
+            "read_by": [],
+            "created_at": "2026-10-04T12:00:00Z",
+            "edited_at": null,
+            "is_deleted": false,
+            "client_temp_id": "c-1"
+          },
+          "my_role": null,
+          "created_at": "2026-10-04T12:00:00Z"
+        }
+      }
+    },
+    "server/chat_deleted.json": {
+      "type": "chat_deleted",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {}
+    },
+    "server/chat_list_update.json": {
+      "type": "chat_list_update",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "chat": {
+          "id": "42",
+          "type": "direct",
+          "name": "Alice",
+          "avatar_url": "/api/v2/users/1001/avatar",
+          "peer": {
+            "id": "1001",
+            "username": "alice",
+            "display_name": "Alice",
+            "avatar_url": "/api/v2/users/1001/avatar",
+            "bio": null,
+            "is_online": true,
+            "last_seen": null,
+            "is_deleted": false
+          },
+          "is_pinned": false,
+          "unread_count": 1,
+          "last_message": {
+            "id": "7217400317439950001",
+            "chat_id": "42",
+            "type": "text",
+            "sender": {
+              "id": "1001",
+              "username": "alice",
+              "display_name": "Alice",
+              "avatar_url": "/api/v2/users/1001/avatar",
+              "bio": null,
+              "is_online": true,
+              "last_seen": null,
+              "is_deleted": false
+            },
+            "content": "Hello!",
+            "attachment": null,
+            "reply_to": null,
+            "forwarded_from": null,
+            "reactions": [],
+            "read_by": [],
+            "created_at": "2026-10-04T12:00:00Z",
+            "edited_at": null,
+            "is_deleted": false,
+            "client_temp_id": "c-1"
+          },
+          "my_role": null,
+          "created_at": "2026-10-04T12:00:00Z"
+        }
+      }
+    },
+    "server/delete.json": {
+      "type": "delete",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "scope": "everyone"
+      }
+    },
+    "server/edit.json": {
+      "type": "edit",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message": {
+          "id": "7217400317439950001",
+          "chat_id": "42",
+          "type": "text",
+          "sender": {
+            "id": "1001",
+            "username": "alice",
+            "display_name": "Alice",
+            "avatar_url": "/api/v2/users/1001/avatar",
+            "bio": null,
+            "is_online": true,
+            "last_seen": null,
+            "is_deleted": false
+          },
+          "content": "Hello, world!",
+          "attachment": null,
+          "reply_to": null,
+          "forwarded_from": null,
+          "reactions": [],
+          "read_by": [],
+          "created_at": "2026-10-04T12:00:00Z",
+          "edited_at": "2026-10-04T12:00:00Z",
+          "is_deleted": false,
+          "client_temp_id": "c-1"
+        }
+      }
+    },
+    "server/error.json": {
+      "type": "error",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "code": "forbidden",
+        "message": "You are not a member of this chat"
+      },
+      "client_temp_id": "c-1"
+    },
+    "server/group_created.json": {
+      "type": "group_created",
+      "event_id": "7217400317439950009",
+      "chat_id": "77",
+      "data": {
+        "group": {
+          "id": "77",
+          "name": "Team",
+          "description": null,
+          "avatar_url": null,
+          "owner_id": "1001",
+          "my_role": "owner",
+          "members": [
+            {
+              "user": {
+                "id": "1001",
+                "username": "alice",
+                "display_name": "Alice",
+                "avatar_url": "/api/v2/users/1001/avatar",
+                "bio": null,
+                "is_online": true,
+                "last_seen": null,
+                "is_deleted": false
+              },
+              "role": "owner",
+              "joined_at": "2026-10-04T12:00:00Z"
+            }
+          ],
+          "created_at": "2026-10-04T12:00:00Z"
+        }
+      }
+    },
+    "server/group_updated.json": {
+      "type": "group_updated",
+      "event_id": "7217400317439950009",
+      "chat_id": "77",
+      "data": {
+        "group": {
+          "id": "77",
+          "name": "Team",
+          "description": null,
+          "avatar_url": null,
+          "owner_id": "1001",
+          "my_role": "owner",
+          "members": [
+            {
+              "user": {
+                "id": "1001",
+                "username": "alice",
+                "display_name": "Alice",
+                "avatar_url": "/api/v2/users/1001/avatar",
+                "bio": null,
+                "is_online": true,
+                "last_seen": null,
+                "is_deleted": false
+              },
+              "role": "owner",
+              "joined_at": "2026-10-04T12:00:00Z"
+            }
+          ],
+          "created_at": "2026-10-04T12:00:00Z"
+        }
+      }
+    },
+    "server/hello.json": {
+      "type": "hello",
+      "event_id": "7217400317439950009",
+      "chat_id": null,
+      "data": {
+        "api_version": "2.0.0-alpha.1",
+        "min_client_api_version": "2.0.0-alpha.1",
+        "user_id": "1001"
+      }
+    },
+    "server/message.json": {
+      "type": "message",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message": {
+          "id": "7217400317439950001",
+          "chat_id": "42",
+          "type": "text",
+          "sender": {
+            "id": "1001",
+            "username": "alice",
+            "display_name": "Alice",
+            "avatar_url": "/api/v2/users/1001/avatar",
+            "bio": null,
+            "is_online": true,
+            "last_seen": null,
+            "is_deleted": false
+          },
+          "content": "Hello!",
+          "attachment": null,
+          "reply_to": null,
+          "forwarded_from": null,
+          "reactions": [],
+          "read_by": [],
+          "created_at": "2026-10-04T12:00:00Z",
+          "edited_at": null,
+          "is_deleted": false,
+          "client_temp_id": "c-1"
+        }
+      }
+    },
+    "server/presence.json": {
+      "type": "presence",
+      "event_id": "7217400317439950009",
+      "chat_id": null,
+      "data": {
+        "user_id": "1002",
+        "is_online": false,
+        "last_seen": "2026-10-04T12:00:00Z"
+      }
+    },
+    "server/reaction_add.json": {
+      "type": "reaction_add",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "reaction": {
+          "emoji": "👍",
+          "user_id": "1002"
+        }
+      }
+    },
+    "server/reaction_remove.json": {
+      "type": "reaction_remove",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "reaction": {
+          "emoji": "👍",
+          "user_id": "1002"
+        }
+      }
+    },
+    "server/read.json": {
+      "type": "read",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "message_id": "7217400317439950001",
+        "user_id": "1002",
+        "read_at": "2026-10-04T12:00:00Z"
+      }
+    },
+    "server/typing.json": {
+      "type": "typing",
+      "event_id": "7217400317439950009",
+      "chat_id": "42",
+      "data": {
+        "user_id": "1002",
+        "is_typing": true
+      }
+    }
+  }
+}