@myronsi/messenger-api 2.1.0-alpha.14 → 2.1.0-alpha.15

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, 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",
+  "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 |\n| `call_updated` | A call of the chat changed (state, participants, epoch); carries the whole call, keep the highest `version` |\n| `call_keys` | Sealed call sender keys for this session only (`docs/calls-e2ee.md`) |\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",
@@ -104,6 +104,70 @@
         }
       }
     },
+    "server/call_keys.json": {
+      "type": "call_keys",
+      "event_id": "7217400317439950111",
+      "chat_id": "77",
+      "data": {
+        "call_id": "7217400317439950100",
+        "epoch": 2,
+        "items": [
+          {
+            "epoch": 2,
+            "sender_user_id": "1002",
+            "sender_session_id": "9c1d2e3f-4a5b-4c6d-8e7f-001122334455",
+            "recipient_session_id": "5b0e8f0a-3f1c-4a52-9a8e-0d6e1c3f9b21",
+            "enc": "BJCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC",
+            "ciphertext": "DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD"
+          }
+        ]
+      }
+    },
+    "server/call_updated.json": {
+      "type": "call_updated",
+      "event_id": "7217400317439950110",
+      "chat_id": "77",
+      "data": {
+        "call": {
+          "id": "7217400317439950100",
+          "chat_id": "77",
+          "kind": "group",
+          "state": "active",
+          "end_reason": null,
+          "initiator_id": "1001",
+          "created_at": "2026-11-07T12:00:00Z",
+          "started_at": "2026-11-07T12:00:05Z",
+          "ended_at": null,
+          "ring_expires_at": "2026-11-07T12:00:30Z",
+          "epoch": 2,
+          "version": 4,
+          "max_participants": 10,
+          "participants": [
+            {
+              "user_id": "1001",
+              "state": "joined",
+              "session_id": "5b0e8f0a-3f1c-4a52-9a8e-0d6e1c3f9b21",
+              "identity_key": "BAt2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+              "joined_at": "2026-11-07T12:00:01Z"
+            },
+            {
+              "user_id": "1002",
+              "state": "joined",
+              "session_id": "9c1d2e3f-4a5b-4c6d-8e7f-001122334455",
+              "identity_key": "BHk9BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+              "joined_at": "2026-11-07T12:00:05Z"
+            },
+            {
+              "user_id": "1003",
+              "state": "ringing",
+              "session_id": null,
+              "identity_key": null,
+              "joined_at": null
+            }
+          ]
+        }
+      }
+    },
     "server/chat_created.json": {
       "type": "chat_created",
       "event_id": "7217400317439950009",

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.14. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.15. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -34,6 +34,8 @@ export type AttachmentRef = string;
 export type ServerEvent =
   | ServerAckEvent
   | ServerApprovalRequestCreatedEvent
+  | ServerCallKeysEvent
+  | ServerCallUpdatedEvent
   | ServerChatCreatedEvent
   | ServerChatDeletedEvent
   | ServerChatListUpdateEvent
@@ -56,10 +58,31 @@ export type Timestamp = string;
 export type ApprovalRequestType = "direct_message" | "group_invite";
 export type ApprovalRequestStatus = "pending" | "approved" | "rejected";
 export type Username = string;
+/**
+ * `ringing` until someone answers, `active` while people are in it, `ended` afterwards.
+ */
+export type CallState = "ringing" | "active" | "ended";
+/**
+ * Why the call ended: `completed` (people talked), `missed` (nobody answered in time), `declined` (the peer of a
+ * direct call declined), `cancelled` (the caller hung up before an answer), `failed` (the media service lost
+ * the call).
+ *
+ */
+export type CallEndReason = "completed" | "missed" | "declined" | "cancelled" | "failed";
+/**
+ * `left` and `declined` can become `joined` again in a group call.
+ */
+export type CallParticipantState = "ringing" | "joined" | "declined" | "missed" | "left";
+/**
+ * P-256 public key as an uncompressed point (65 bytes, first byte `0x04`), base64url without padding.
+ *
+ */
+export type CallIdentityKey = string;
 export type ChatType = "direct" | "group";
 export type MessageType = "text" | "file" | "voice" | "system";
 export type AttachmentKind = "image" | "audio" | "voice" | "video" | "file";
-export type SystemEventKind = "group_created" | "member_added" | "member_joined" | "member_removed" | "member_left";
+export type SystemEventKind =
+  "group_created" | "member_added" | "member_joined" | "member_removed" | "member_left" | "call";
 /**
  * A moderator may delete other members' messages; owners and admins also manage the group.
  */
@@ -88,6 +111,13 @@ export type ErrorCode =
   | "invalid_client_version"
   | "blocked_by_user"
   | "approval_required"
+  | "calls_unavailable"
+  | "calls_not_allowed"
+  | "call_identity_required"
+  | "call_full"
+  | "call_ended"
+  | "already_in_call"
+  | "stale_epoch"
   | "internal_error";
 
 /**
@@ -267,6 +297,95 @@ export interface User {
   last_seen: Timestamp | null;
   is_deleted: boolean;
 }
+/**
+ * Sealed sender keys for this session (see docs/calls-e2ee.md). Sent only to the recipient session.
+ */
+export interface ServerCallKeysEvent {
+  type: "call_keys";
+  event_id: Id;
+  chat_id: Id;
+  data: CallKeyEnvelopeList;
+}
+export interface CallKeyEnvelopeList {
+  call_id: Id;
+  epoch: number;
+  items: CallKeyEnvelope[];
+}
+/**
+ * An HPKE Auth-mode envelope carrying one sender key (see `docs/calls-e2ee.md`).
+ */
+export interface CallKeyEnvelope {
+  epoch: number;
+  sender_user_id: Id;
+  sender_session_id: string;
+  recipient_session_id: string;
+  /**
+   * HPKE encapsulated key, base64url without padding.
+   */
+  enc: string;
+  /**
+   * Sealed sender key, base64url without padding.
+   */
+  ciphertext: string;
+}
+/**
+ * A call of the chat started, rang, changed participants or epoch, or ended. Carries the whole call; keep the one with the highest `version`. Sent to every member of the chat.
+ */
+export interface ServerCallUpdatedEvent {
+  type: "call_updated";
+  event_id: Id;
+  chat_id: Id;
+  data: {
+    call: Call;
+  };
+}
+export interface Call {
+  id: Id;
+  chat_id: Id;
+  kind: "direct" | "group";
+  state: CallState;
+  end_reason: CallEndReason | null;
+  initiator_id: Id;
+  created_at: Timestamp;
+  /**
+   * First answer; `null` while nobody answered.
+   */
+  started_at: Timestamp | null;
+  ended_at: Timestamp | null;
+  /**
+   * When ringing invitations of this call turn into `missed`.
+   */
+  ring_expires_at: string;
+  /**
+   * Key epoch; increases whenever the set of joined sessions or their identity keys change.
+   */
+  epoch: number;
+  /**
+   * Increases with every change of the call; ignore events with a lower version than one already seen.
+   */
+  version: number;
+  max_participants: number;
+  /**
+   * Everyone invited or joined, the initiator first.
+   */
+  participants: CallParticipant[];
+}
+export interface CallParticipant {
+  user_id: Id;
+  state: CallParticipantState;
+  /**
+   * The session that joined; `null` unless `state` is `joined`.
+   */
+  session_id: string | null;
+  /**
+   * Call identity of the joined session; `null` unless `state` is `joined`.
+   */
+  identity_key: CallIdentityKey | null;
+  /**
+   * When the participant last joined; `null` if never.
+   */
+  joined_at: Timestamp | null;
+}
 /**
  * A chat was created with you.
  */
@@ -382,7 +501,8 @@ export interface ReadReceipt {
 /**
  * What a `system` message records; set on system messages only, whose `content` is then `null`. The names
  * are the display names at the time of the event. `target` fields are set for `member_added` and
- * `member_removed`.
+ * `member_removed`. `call` is set for `call` messages: one per call, posted when the call ends, `actor` is the
+ * initiator.
  *
  */
 export interface SystemEvent {
@@ -391,6 +511,19 @@ export interface SystemEvent {
   actor_name: string;
   target_id?: Id;
   target_name?: string;
+  call?: CallSummary;
+}
+/**
+ * The call a `call` system message records.
+ */
+export interface CallSummary {
+  call_id: Id;
+  kind: "direct" | "group";
+  outcome: CallEndReason;
+  /**
+   * From the first answer to the end; `null` if nobody answered.
+   */
+  duration_seconds: number | null;
 }
 /**
  * A chat was deleted, or you were removed from it.