@myronsi/messenger-api 2.0.0-alpha.2.next.34 → 2.0.0-alpha.3.next.42

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.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.3. Do not edit. */
+export declare const API_VERSION: "2.0.0-alpha.3";
 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.3";

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.3
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and

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.3. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {

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.3. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.

package/package.json

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